Hugging Face's logo

Spaces:
eduverse-team
/
eduverse-backend
Sleeping

App Files Community
eduverse-backend / COURSES_ASSIGNMENTS_LABS_BACKEND_API_DOCS.md
amirhamdi's picture
amirhamdi
1 fix(google-drive): add self-healing folder management with duplicate prevention
b4c4de1
preview code
|
Raw
History Blame Contribute Delete
152 kB
# 📖 EduVerse API Documentation — Courses / Assignments / Labs
> **Purpose**: Complete Flutter frontend integration guide.
> **Base URL**: `http://<host>:3001` (default port `3001`)
> **Auth**: Most endpoints require `Authorization: Bearer <JWT>` header.
> **Content-Type**: `application/json` unless otherwise noted (file uploads use `multipart/form-data`).
---
## Table of Contents
1. [Global Information](#1-global-information)
2. [Enums Reference](#2-enums-reference)
3. [Courses Module](#3-courses-module)
4. [Course Sections Module](#4-course-sections-module)
5. [Course Schedules Module](#5-course-schedules-module)
6. [Assignments Module](#6-assignments-module)
7. [Labs Module](#7-labs-module)
8. [Role-Based Access Matrix](#8-role-based-access-matrix)
9. [Error Handling](#9-error-handling)
10. [Flutter Integration Tips](#10-flutter-integration-tips)
11. [Course Materials & Video Lectures Module](#11-course-materials--video-lectures-module)
12. [Course Structure Module](#12-course-structure-module)
13. [YouTube Integration Module](#13-youtube-integration-module)
---
## 1. Global Information
### 1.1 Authentication
All **authenticated endpoints** require the header:
```
Authorization: Bearer <access_token>
```
The token is obtained from `POST /api/auth/login`.
### 1.2 Roles
| Role Enum Value | Display Name | Description |
|---|---|---|
| `student` | Student | Regular student users |
| `instructor` | Instructor | Faculty members |
| `teaching_assistant` | TA | Teaching assistants |
| `admin` | Admin | Administrative staff |
| `it_admin` | IT Admin | Full system access |
| `department_head` | Department Head | Department leadership |
### 1.3 Pagination Response Shape
All paginated endpoints return:
```json
{
 "data": [ /* array of items */ ],
 "meta": {
 "total": 150, // integer — total matching records
 "page": 1, // integer — current page number
 "limit": 20, // integer — items per page
 "totalPages": 8 // integer — total number of pages
 }
}
```
### 1.4 Validation Rules
The API uses `class-validator` with:
- `whitelist: true` — unknown properties are **stripped**
- `forbidNonWhitelisted: true` — unknown properties cause **400 error**
- `transform: true` — query strings auto-converted to proper types
---
## 2. Enums Reference
### 2.1 Course Enums
#### CourseLevel
| Value | Description |
|---|---|
| `FRESHMAN` | Freshman-level course |
| `SOPHOMORE` | Sophomore-level course |
| `JUNIOR` | Junior-level course |
| `SENIOR` | Senior-level course |
| `GRADUATE` | Graduate-level course |
#### CourseStatus
| Value | Description |
|---|---|
| `ACTIVE` | Course is currently active |
| `INACTIVE` | Course is inactive |
| `ARCHIVED` | Course is archived |
#### SectionStatus
| Value | Description |
|---|---|
| `OPEN` | Section accepting enrollments |
| `CLOSED` | Section manually closed |
| `FULL` | Section at max capacity |
| `CANCELLED` | Section cancelled |
#### ScheduleType
| Value | Description |
|---|---|
| `LECTURE` | Lecture session |
| `LAB` | Laboratory session |
| `TUTORIAL` | Tutorial/recitation session |
| `EXAM` | Examination session |
#### DayOfWeek
| Value |
|---|
| `MONDAY` |
| `TUESDAY` |
| `WEDNESDAY` |
| `THURSDAY` |
| `FRIDAY` |
| `SATURDAY` |
| `SUNDAY` |
### 2.2 Assignment Enums
#### SubmissionType
| Value | Description |
|---|---|
| `file` | File-based submission |
| `text` | Text-based submission |
| `link` | Link/URL submission |
| `multiple` | Combination of types |
#### AssignmentStatus
| Value | Description |
|---|---|
| `draft` | Not visible to students |
| `published` | Visible and accepting submissions |
| `closed` | No longer accepting submissions |
| `archived` | Hidden from all views |
> **Status Transitions**: `draft` → `published` → `closed` → `archived` (one-way only)
#### SubmissionStatus
| Value | Description |
|---|---|
| `submitted` | Student has submitted |
| `graded` | Submission has been graded |
| `returned` | Returned to student for review |
| `resubmit` | Student must resubmit |
### 2.3 Lab Enums
#### LabStatus
| Value | Description |
|---|---|
| `draft` | Not visible to students |
| `published` | Visible and accepting submissions |
| `closed` | No longer accepting submissions |
| `archived` | Hidden from all views |
#### LabSubmissionStatus
| Value | Description |
|---|---|
| `submitted` | Student has submitted |
| `graded` | Submission has been graded |
| `returned` | Returned to student |
| `resubmit` | Student must resubmit |
#### LabAttendanceStatus
| Value | Description |
|---|---|
| `present` | Student was present |
| `absent` | Student was absent |
| `excused` | Excused absence |
| `late` | Student arrived late |
---
## 3. Courses Module
**Base Path**: `/api/courses`
> **Authentication**: Courses listing/viewing endpoints are **public** (no auth required).
> Course creation/update/delete endpoints need authentication and specific roles.
---
### 3.1 List All Courses
```
GET /api/courses
```
**Auth Required**: ❌ No (Public)
**Roles**: All (public endpoint)
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `departmentId` | `integer` | ❌ | — | Filter by department ID |
| `level` | `string` | ❌ | — | Filter by course level enum (e.g. `FRESHMAN`, `GRADUATE`) |
| `status` | `string` | ❌ | — | Filter by `CourseStatus` enum (`ACTIVE`, `INACTIVE`, `ARCHIVED`) |
| `search` | `string` | ❌ | — | Search in course name or code (partial match) |
| `page` | `integer` | ❌ | `1` | Page number (1-indexed) |
| `limit` | `integer` | ❌ | `20` | Items per page (max 100) |
#### Response `200 OK`
```json
{
 "data": [
 {
 "id": 1, // number — Course ID (bigint)
 "departmentId": 3, // number — FK to departments
 "name": "Introduction to CS", // string — Course name
 "code": "CS101", // string — Unique course code
 "description": "Fundamentals of...", // string | null — Description
 "credits": 3, // number — Credit hours (1-6)
 "level": "FRESHMAN", // string — CourseLevel enum
 "syllabusUrl": "https://...", // string | null — Syllabus URL
 "instructorId": 5, // number | null — Assigned instructor
 "taIds": [1, 2], // number[] | null — Assigned TA IDs
 "status": "ACTIVE", // string — CourseStatus enum
 "createdAt": "2025-01-15T10:00:00Z", // string (ISO 8601) — Creation timestamp
 "updatedAt": "2025-01-15T10:00:00Z", // string (ISO 8601) — Last update
 "department": { // object — Joined department info
 "id": 3,
 "name": "Computer Science",
 "code": "CS"
 }
 }
 ],
 "meta": {
 "total": 42,
 "page": 1,
 "limit": 20,
 "totalPages": 3
 }
}
```
---
### 3.2 Get Courses by Department
```
GET /api/courses/department/:deptId
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `deptId` | `integer` | ✅ | Department ID |
#### Response `200 OK`
Returns an **array** of course objects (same shape as items in `data` array above, including `department` relation).
#### Error Responses
| Status | Description |
|---|---|
| `404` | Department not found |
---
### 3.3 Get Course by ID
```
GET /api/courses/:id
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID |
#### Response `200 OK`
```json
{
 "id": 1,
 "departmentId": 3,
 "name": "Introduction to CS",
 "code": "CS101",
 "description": "Fundamentals of programming...",
 "credits": 3,
 "level": "FRESHMAN",
 "syllabusUrl": "https://example.com/syllabus.pdf",
 "instructorId": 5,
 "taIds": [1, 2],
 "status": "ACTIVE",
 "createdAt": "2025-01-15T10:00:00Z",
 "updatedAt": "2025-01-15T10:00:00Z",
 "department": {
 "id": 3,
 "name": "Computer Science",
 "code": "CS"
 },
 "prerequisites": [], // CoursePrerequisite[] — loaded relation
 "sections": [], // CourseSection[] — loaded relation
 "prerequisitesCount": 0, // number — count of prerequisites
 "sectionsCount": 2 // number — count of active sections
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | Course not found |
---
### 3.4 Create Course
```
POST /api/courses
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `departmentId` | `number` | ✅ | Must exist | Department to assign course to |
| `name` | `string` | ✅ | — | Course name |
| `code` | `string` | ✅ | 2-10 uppercase alphanumeric (`/^[A-Z0-9]{2,10}$/`) | Unique course code |
| `description` | `string` | ✅ | — | Course description |
| `credits` | `integer` | ✅ | 1–6 | Credit hours |
| `level` | `string` | ✅ | `CourseLevel` enum | Course level |
| `syllabusUrl` | `string` | ❌ | Valid URL | Syllabus URL |
| `instructorId` | `number` | ❌ | Must reference valid user | Instructor user ID |
| `taIds` | `number[]` | ❌ | Array of valid user IDs | TA user IDs |
#### Example Request
```json
{
 "departmentId": 1,
 "name": "Introduction to Computer Science",
 "code": "CS101",
 "description": "Fundamentals of programming and computational thinking.",
 "credits": 3,
 "level": "FRESHMAN",
 "syllabusUrl": "https://example.com/syllabus/cs101.pdf",
 "instructorId": 5,
 "taIds": [10, 11]
}
```
#### Response `201 Created`
Returns the created course object (same shape as Get Course by ID, without `prerequisitesCount`/`sectionsCount`).
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data / validation failure |
| `404` | Department not found |
| `409` | Course code already exists in department |
---
### 3.5 Update Course
```
PATCH /api/courses/:id
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID |
#### Request Body (`application/json`) — All fields optional
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `name` | `string` | ❌ | — | Updated course name |
| `description` | `string` | ❌ | — | Updated description |
| `credits` | `integer` | ❌ | 1–6 | Updated credit hours |
| `level` | `string` | ❌ | `CourseLevel` enum | Updated course level |
| `syllabusUrl` | `string` | ❌ | — | Updated syllabus URL |
| `status` | `string` | ❌ | `CourseStatus` enum | Change course status |
| `instructorId` | `number` | ❌ | — | Change instructor |
| `taIds` | `number[]` | ❌ | — | Change TAs |
#### Response `200 OK`
Returns the updated course object.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data |
| `404` | Course not found |
---
### 3.6 Delete Course (Soft Delete)
```
DELETE /api/courses/:id
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID |
#### Response `204 No Content`
Empty body.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Cannot delete course with active enrollments |
| `404` | Course not found |
---
### 3.7 Get Course Prerequisites
```
GET /api/courses/:id/prerequisites
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID |
#### Response `200 OK`
```json
[
 {
 "id": 1, // number — Prerequisite record ID
 "courseId": 5, // number — The course that has this prerequisite
 "prerequisiteCourseId": 2, // number — The required prereq course ID
 "isMandatory": true, // boolean — Whether this prereq is mandatory
 "prerequisiteCourse": { // object — Joined prerequisite course info
 "id": 2,
 "name": "Programming Basics",
 "code": "CS100",
 "level": "FRESHMAN"
 },
 "createdAt": "2025-01-10T08:00:00Z" // string (ISO 8601)
 }
]
```
---
### 3.8 Add Prerequisite
```
POST /api/courses/:id/prerequisites
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID to add prerequisite to |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `prerequisiteCourseId` | `number` | ✅ | ID of the prerequisite course |
| `isMandatory` | `boolean` | ✅ | Whether this prerequisite is mandatory |
#### Example Request
```json
{
 "prerequisiteCourseId": 2,
 "isMandatory": true
}
```
#### Response `201 Created`
Returns the created prerequisite record.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Circular dependency detected / Self-prerequisite |
| `404` | Course or prerequisite course not found |
| `409` | Prerequisite already exists |
---
### 3.9 Remove Prerequisite
```
DELETE /api/courses/:id/prerequisites/:prereqId
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Course ID |
| `prereqId` | `integer` | ✅ | Prerequisite record ID |
#### Response `204 No Content`
Empty body.
---
## 4. Course Sections Module
**Base Path**: `/api/sections`
---
### 4.1 Get Sections by Course
```
GET /api/sections/course/:courseId
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `semesterId` | `integer` | ❌ | — | Filter by semester |
#### Response `200 OK`
```json
[
 {
 "id": 11, // number — Section ID (bigint)
 "courseId": 1, // number — FK to courses
 "semesterId": 1, // number — FK to semesters
 "sectionNumber": "1", // string — Section number
 "maxCapacity": 30, // number — Maximum students
 "currentEnrollment": 25, // number — Currently enrolled
 "location": "Room A101", // string | null — Room/location
 "status": "OPEN", // string — SectionStatus enum
 "createdAt": "2025-01-15T10:00:00Z",
 "updatedAt": "2025-01-15T10:00:00Z",
 "course": {
 "id": 1,
 "name": "Introduction to CS",
 "code": "CS101"
 },
 "semester": {
 "id": 1,
 "name": "Fall 2025",
 "startDate": "2025-09-01",
 "endDate": "2025-12-15"
 },
 "schedules": [
 {
 "id": 1,
 "dayOfWeek": "MONDAY", // DayOfWeek enum
 "startTime": "09:00", // string (HH:mm)
 "endTime": "10:30", // string (HH:mm)
 "room": "A101", // string | null
 "building": "Main Building", // string | null
 "scheduleType": "LECTURE" // ScheduleType enum
 }
 ]
 }
]
```
---
### 4.2 Get Section by ID
```
GET /api/sections/:id
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Section ID |
#### Response `200 OK`
Same shape as a single item from the array above (includes `course`, `semester`, `schedules` relations).
---
### 4.3 Create Section
```
POST /api/sections
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
#### Request Body
| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `courseId` | `number` | ✅ | — | Must exist | Course to create section for |
| `semesterId` | `number` | ✅ | — | Must exist | Semester ID |
| `sectionNumber` | `integer` | ❌ | Auto-generated | >= 1 | Section number |
| `maxCapacity` | `integer` | ✅ | — | >= 1 | Maximum student capacity |
| `currentEnrollment` | `integer` | ❌ | `0` | >= 0 | Current enrollment count |
| `location` | `string` | ❌ | `null` | — | Room/location |
#### Example Request
```json
{
 "courseId": 1,
 "semesterId": 1,
 "maxCapacity": 30,
 "location": "Room A101"
}
```
#### Response `201 Created`
Returns the created section object.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data |
| `404` | Course or semester not found |
| `409` | Section number already exists for this course/semester combo |
---
### 4.4 Update Section
```
PATCH /api/sections/:id
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor` (section owner)
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Section ID |
#### Request Body — All fields optional
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `maxCapacity` | `integer` | ❌ | >= 1, cannot be less than current enrollment | Updated max capacity |
| `currentEnrollment` | `integer` | ❌ | >= 0 | Updated enrollment count |
| `location` | `string` | ❌ | — | Updated location |
| `status` | `string` | ❌ | `SectionStatus` enum | Change section status |
#### Response `200 OK`
Returns the updated section object.
---
### 4.5 Update Section Enrollment Count
```
PATCH /api/sections/:id/enrollment
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
> Typically called automatically by the enrollment system.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Section ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `currentEnrollment` | `number` | ✅ | New enrollment count |
#### Response `200 OK`
Returns the updated section object with recalculated status.
---
## 5. Course Schedules Module
**Base Path**: `/api/schedules`
---
### 5.1 Get Schedules by Section
```
GET /api/schedules/section/:sectionId
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
```json
[
 {
 "id": 1, // number — Schedule ID
 "sectionId": 11, // number — FK to sections
 "dayOfWeek": "MONDAY", // string — DayOfWeek enum
 "startTime": "09:00", // string — HH:mm format (24-hour)
 "endTime": "10:30", // string — HH:mm format (24-hour)
 "room": "A101", // string | null
 "building": "Main Building", // string | null
 "scheduleType": "LECTURE", // string — ScheduleType enum
 "createdAt": "2025-01-15T10:00:00Z"
 }
]
```
---
### 5.2 Get Schedule by ID
```
GET /api/schedules/:id
```
**Auth Required**: ❌ No (Public)
**Roles**: All
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Schedule ID |
#### Response `200 OK`
Returns single schedule object with `section` relation included.
---
### 5.3 Create Schedule
```
POST /api/schedules/section/:sectionId
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section to add schedule to |
#### Request Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `dayOfWeek` | `string` | ✅ | `DayOfWeek` enum | Day of week |
| `startTime` | `string` | ✅ | HH:mm format 24-hour (`/^([0-1][0-9]\|2[0-3]):[0-5][0-9]$/`) | Start time |
| `endTime` | `string` | ✅ | HH:mm format (same regex, must be after startTime) | End time |
| `room` | `string` | ❌ | — | Room number/name |
| `building` | `string` | ❌ | — | Building name |
| `scheduleType` | `string` | ✅ | `ScheduleType` enum | Type of session |
#### Example Request
```json
{
 "dayOfWeek": "MONDAY",
 "startTime": "09:00",
 "endTime": "10:30",
 "room": "A101",
 "building": "Main Building",
 "scheduleType": "LECTURE"
}
```
#### Response `201 Created`
Returns the created schedule object.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid time range (end <= start) or schedule conflict detected |
| `404` | Section not found |
---
### 5.4 Delete Schedule
```
DELETE /api/schedules/:id
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `it_admin`, `instructor`
#### Response `204 No Content`
Empty body.
---
## 6. Assignments Module
**Base Path**: `/api/assignments`
> **All endpoints require JWT authentication** (`@UseGuards(JwtAuthGuard, RolesGuard)`).
---
### 6.1 List Assignments
```
GET /api/assignments
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `courseId` | `integer` | ❌ | — | Filter by course ID |
| `sectionId` | `integer` | ❌ | — | Filter by section ID |
| `status` | `string` | ❌ | — | Filter by `AssignmentStatus` enum (`draft`, `published`, `closed`, `archived`) |
| `dueBefore` | `string` | ❌ | — | Filter assignments due before this date (ISO 8601) |
| `dueAfter` | `string` | ❌ | — | Filter assignments due after this date (ISO 8601) |
| `search` | `string` | ❌ | — | Search in assignment title (partial match) |
| `page` | `integer` | ❌ | `1` | Page number |
| `limit` | `integer` | ❌ | `10` | Items per page |
| `sortBy` | `string` | ❌ | `createdAt` | Sort field: `dueDate`, `createdAt`, `title` |
| `sortOrder` | `string` | ❌ | `DESC` | Sort order: `ASC` or `DESC` |
#### Response `200 OK`
```json
{
 "data": [
 {
 "id": 3, // number — Assignment ID (bigint)
 "courseId": 1, // number — FK to courses
 "title": "Homework 1 - Binary Search", // string — Assignment title
 "description": "Implement binary search...", // string | null
 "instructions": "Submit as .zip file...", // string | null
 "maxScore": 100.00, // number (decimal) — Maximum possible score
 "weight": 15.00, // number (decimal) — Weight % in final grade
 "dueDate": "2025-06-15T23:59:59Z", // string | null — Due date (ISO 8601)
 "availableFrom": "2025-06-01T00:00:00Z", // string | null — Available from date
 "lateSubmissionAllowed": 0, // number (0 or 1) — 0=false, 1=true
 "latePenaltyPercent": 10.00, // number (decimal) — Late penalty %
 "submissionType": "file", // string — SubmissionType enum
 "maxFileSizeMb": 10, // number — Max file size in MB
 "allowedFileTypes": "[\"pdf\",\"zip\"]", // string | null — JSON string of allowed types
 "status": "published", // string — AssignmentStatus enum
 "createdBy": 5, // number — Creator user ID
 "createdAt": "2025-06-01T08:00:00Z", // string (ISO 8601)
 "updatedAt": "2025-06-01T08:00:00Z", // string (ISO 8601)
 "course": { // object — Joined course info
 "id": 1,
 "departmentId": 3,
 "name": "Introduction to CS",
 "code": "CS101",
 "description": "...",
 "credits": 3,
 "level": "FRESHMAN",
 "status": "ACTIVE"
 }
 }
 ],
 "meta": {
 "total": 12,
 "page": 1,
 "limit": 10,
 "totalPages": 2
 }
}
```
---
### 6.2 Get Assignment Details
```
GET /api/assignments/:id
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Response `200 OK`
```json
{
 "id": 3,
 "courseId": 1,
 "title": "Homework 1 - Binary Search",
 "description": "Implement binary search...",
 "instructions": "Submit as .zip file...",
 "maxScore": 100.00,
 "weight": 15.00,
 "dueDate": "2025-06-15T23:59:59Z",
 "availableFrom": "2025-06-01T00:00:00Z",
 "lateSubmissionAllowed": 0,
 "latePenaltyPercent": 10.00,
 "submissionType": "file",
 "maxFileSizeMb": 10,
 "allowedFileTypes": "[\"pdf\",\"zip\"]",
 "status": "published",
 "createdBy": 5,
 "createdAt": "2025-06-01T08:00:00Z",
 "updatedAt": "2025-06-01T08:00:00Z",
 "course": { /* full course object */ },
 "submissions": [
 {
 "id": 1, // number — Submission ID
 "assignmentId": 3, // number
 "userId": 57, // number — Student user ID
 "submissionText": "My essay...", // string | null
 "submissionLink": "https://...", // string | null
 "fileId": 12, // number | null — FK to files
 "submissionStatus": "submitted", // string — SubmissionStatus enum
 "isLate": 0, // number (0 or 1)
 "attemptNumber": 1, // number — Attempt count
 "submittedAt": "2025-06-10T14:30:00Z",
 "score": null, // number | null — Graded score
 "feedback": null, // string | null — Grader feedback
 "gradedBy": null, // number | null — Grader user ID
 "gradedAt": null, // string | null — Grading timestamp
 "user": {
 "user_id": 57,
 "first_name": "John",
 "last_name": "Doe",
 "email": "john@example.com"
 }
 }
 ]
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | Assignment not found |
---
### 6.3 Create Assignment
```
POST /api/assignments
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`
#### Request Body
| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `courseId` | `number` | ✅ | — | Must exist | Course ID |
| `title` | `string` | ✅ | — | 3-200 chars | Assignment title |
| `description` | `string` | ❌ | `null` | — | Description |
| `instructions` | `string` | ❌ | `null` | — | Detailed instructions |
| `submissionType` | `string` | ❌ | `file` | `SubmissionType` enum | How students submit |
| `maxScore` | `number` | ❌ | `100` | 0-1000 | Maximum score |
| `weight` | `number` | ❌ | `0` | 0-100 | Weight percentage in final grade |
| `dueDate` | `string` | ❌ | `null` | ISO 8601 datetime | Due date |
| `availableFrom` | `string` | ❌ | `null` | ISO 8601 datetime | Available from date |
| `lateSubmissionAllowed` | `boolean` | ❌ | `false` | — | Allow late submissions |
| `latePenaltyPercent` | `number` | ❌ | `0` | 0-100 | Late penalty % |
| `maxFileSizeMb` | `number` | ❌ | `10` | — | Max file size in MB |
| `allowedFileTypes` | `string` | ❌ | `null` | JSON string array | Allowed file extensions |
| `status` | `string` | ❌ | `draft` | `AssignmentStatus` enum | Initial status |
#### Example Request
```json
{
 "courseId": 1,
 "title": "Homework 1 - Binary Search",
 "description": "Implement a binary search tree with insert, delete, and search operations.",
 "instructions": "Submit your code as a single .zip file. Include a README with compilation instructions.",
 "submissionType": "file",
 "maxScore": 100,
 "weight": 15,
 "dueDate": "2025-06-15T23:59:59Z",
 "availableFrom": "2025-06-01T00:00:00Z",
 "lateSubmissionAllowed": true,
 "latePenaltyPercent": 10,
 "maxFileSizeMb": 10,
 "allowedFileTypes": "[\"pdf\",\"docx\",\"zip\"]",
 "status": "draft"
}
```
#### Response `201 Created`
Returns the created assignment with joined `course` relation.
---
### 6.4 Update Assignment
```
PATCH /api/assignments/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Request Body
All fields from `CreateAssignmentDto` are **optional** (uses `PartialType`).
#### Response `200 OK`
Returns the updated assignment object.
---
### 6.5 Delete Assignment (Soft Delete)
```
DELETE /api/assignments/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Response `200 OK`
Empty body (assignment removed).
---
### 6.6 Change Assignment Status
```
PATCH /api/assignments/:id/status
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Request Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `status` | `string` | ✅ | Must follow: `draft` -> `published` -> `closed` -> `archived` | New status |
> **WARNING — Transition rules**: Only the next status in the chain is allowed. You cannot skip statuses. E.g., you cannot go from `draft` directly to `closed`.
#### Example Request
```json
{
 "status": "published"
}
```
#### Response `200 OK`
Returns the updated assignment object.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid status transition |
| `404` | Assignment not found |
---
### 6.7 Submit Assignment (Student)
```
POST /api/assignments/:id/submit
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `submissionText` | `string` | ❌ | Text content for text submissions |
| `fileId` | `number` | ❌ | File ID from the files module (for file submissions) |
| `submissionLink` | `string` | ❌ | External URL (e.g., GitHub repo link) |
> At least one of `submissionText`, `fileId`, or `submissionLink` should be provided.
#### Example Request
```json
{
 "submissionText": "This is my essay submission about data structures...",
 "submissionLink": "https://github.com/student/project"
}
```
#### Response `201 Created` (via POST)
```json
{
 "id": 15, // number — Submission ID
 "assignmentId": 3, // number
 "userId": 57, // number — From JWT
 "submissionText": "This is my essay...",
 "submissionLink": "https://github.com/student/project",
 "fileId": null,
 "submissionStatus": "submitted",
 "isLate": 0, // number — 0=on-time, 1=late
 "attemptNumber": 1, // number — Auto-incremented
 "submittedAt": "2025-06-10T14:30:00Z",
 "score": null,
 "feedback": null,
 "gradedBy": null,
 "gradedAt": null
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Student not enrolled in course / Late submission not allowed / Assignment not available yet |
| `404` | Assignment not found |
#### Business Rules
- Assignment must be in `published` status
- If `availableFrom` is set, current time must be after it
- If `dueDate` is set and past, `lateSubmissionAllowed` must be `true` (otherwise 400)
- Auto-marks `isLate = 1` if submitted after `dueDate`
- Auto-increments `attemptNumber`
- Student must be enrolled in the assignment's course
---
### 6.8 Get My Submission (Student)
```
GET /api/assignments/:id/submissions/my
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Response `200 OK`
Returns the student's **latest** submission (highest `attemptNumber`):
```json
{
 "id": 15,
 "assignmentId": 3,
 "userId": 57,
 "submissionText": "My submission...",
 "submissionLink": null,
 "fileId": 12,
 "submissionStatus": "graded",
 "isLate": 0,
 "attemptNumber": 2,
 "submittedAt": "2025-06-10T14:30:00Z",
 "score": 85.00,
 "feedback": "Well done! Consider improving error handling.",
 "gradedBy": 5,
 "gradedAt": "2025-06-12T10:00:00Z"
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | No submission found for this student/assignment |
---
### 6.9 List All Submissions (Instructor/TA/Admin)
```
GET /api/assignments/:id/submissions
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Response `200 OK`
```json
[
 {
 "id": 15,
 "assignmentId": 3,
 "userId": 57,
 "submissionText": "My submission...",
 "submissionLink": null,
 "fileId": 12,
 "submissionStatus": "submitted",
 "isLate": 0,
 "attemptNumber": 1,
 "submittedAt": "2025-06-10T14:30:00Z",
 "score": null,
 "feedback": null,
 "gradedBy": null,
 "gradedAt": null,
 "user": {
 "user_id": 57,
 "first_name": "John",
 "last_name": "Doe",
 "email": "john@example.com"
 }
 }
]
```
> Returns submissions sorted by `submittedAt` DESC.
---
### 6.10 Grade a Submission
```
PATCH /api/assignments/:id/submissions/:subId/grade
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
| `subId` | `integer` | ✅ | Submission ID |
#### Request Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `score` | `number` | ✅ | >= 0 | Numeric score |
| `feedback` | `string` | ❌ | — | Feedback comments |
#### Example Request
```json
{
 "score": 85,
 "feedback": "Well done! Consider improving the conclusion."
}
```
#### Response `200 OK`
```json
{
 "submissionId": 15, // number — Graded submission ID
 "score": 85, // number — Score assigned
 "maxScore": 100, // number — Assignment max score
 "feedback": "Well done!", // string | undefined
 "gradeId": 42 // number — Created grade record ID in central gradebook
}
```
> **Side effect**: Also creates a grade record in the central `grades` table with `gradeType = 'assignment'`, `isPublished = true`.
---
### 6.11 Upload Assignment Instruction (Google Drive)
```
POST /api/assignments/:id/instructions/upload
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`
**Content-Type**: `multipart/form-data`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `file` | `binary` | ✅ | PDF, DOCX, etc. | The instruction file |
| `title` | `string` | ❌ | Max 255 chars | Instruction title |
| `orderIndex` | `integer` | ❌ | >= 0, default `0` | Sort order |
#### Response `201 Created`
```json
{
 "assignmentId": 3,
 "driveFile": {
 "driveFileId": 123, // number — Internal drive file record ID
 "driveId": "1abc...", // string — Google Drive file ID
 "fileName": "HW1_Instructions_v1.pdf",
 "webViewLink": "https://drive.google.com/file/d/1abc.../view",
 "webContentLink": "https://drive.google.com/uc?id=1abc..."
 }
}
```
---
### 6.12 Upload Assignment Submission (Google Drive — Student)
```
POST /api/assignments/:id/submissions/upload
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
**Content-Type**: `multipart/form-data`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Assignment ID |
#### Form Data Fields
| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `binary` | ✅ | Submission file |
| `submissionText` | `string` | ❌ | Notes/comments |
| `submissionLink` | `string` | ❌ | External link (e.g., GitHub) |
#### Response `201 Created`
```json
{
 "submission": {
 "id": 16,
 "assignmentId": 3,
 "userId": 57,
 "submissionText": "Completed all tasks.",
 "submissionLink": "https://github.com/student/project",
 "fileId": null,
 "submissionStatus": "submitted",
 "isLate": 0,
 "attemptNumber": 1,
 "submittedAt": "2025-06-10T14:30:00Z",
 "score": null,
 "feedback": null,
 "gradedBy": null,
 "gradedAt": null
 },
 "driveFile": {
 "driveFileId": 124,
 "driveId": "1def...",
 "fileName": "Assignment_3_Submission_20250610.zip",
 "webViewLink": "https://drive.google.com/file/d/1def.../view",
 "webContentLink": "https://drive.google.com/uc?id=1def..."
 },
 "isLate": false // boolean — Whether submission was late
}
```
#### Business Rules
Same as regular submit (section 6.7): must be published, enrolled, respects late submission rules.
---
## 7. Labs Module
**Base Path**: `/api/labs`
> **All endpoints require JWT authentication** (`@UseGuards(JwtAuthGuard, RolesGuard)`).
---
### 7.1 List Labs
```
GET /api/labs
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `courseId` | `integer` | ❌ | — | Filter by course ID |
| `status` | `string` | ❌ | — | Filter by `LabStatus` enum (`draft`, `published`, `closed`, `archived`) |
| `page` | `integer` | ❌ | `1` | Page number (>= 1) |
| `limit` | `integer` | ❌ | `20` | Items per page (1-100) |
#### Response `200 OK`
```json
{
 "data": [
 {
 "id": 1, // number — Lab ID (bigint)
 "courseId": 1, // number — FK to courses
 "title": "Binary Search Lab", // string — Lab title
 "description": "Implement binary...", // string | null
 "labNumber": 1, // number | null — Lab sequence number
 "dueDate": "2026-04-15T23:59:59Z", // string | null — Due date (ISO 8601)
 "availableFrom": "2026-04-01T00:00:00Z", // string | null
 "maxScore": 100.00, // number (decimal) — Max score
 "weight": 10.00, // number (decimal) — Weight in final grade
 "status": "published", // string — LabStatus enum
 "createdBy": 5, // number — Creator user ID
 "createdAt": "2026-04-01T08:00:00Z",
 "updatedAt": "2026-04-01T08:00:00Z",
 "course": {
 "id": 1,
 "departmentId": 3,
 "name": "Introduction to CS",
 "code": "CS101"
 }
 }
 ],
 "meta": {
 "total": 8,
 "page": 1,
 "limit": 20,
 "totalPages": 1
 }
}
```
---
### 7.2 Get Lab by ID
```
GET /api/labs/:id
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `200 OK`
```json
{
 "id": 1,
 "courseId": 1,
 "title": "Binary Search Lab",
 "description": "Implement binary search in Python",
 "labNumber": 1,
 "dueDate": "2026-04-15T23:59:59Z",
 "availableFrom": "2026-04-01T00:00:00Z",
 "maxScore": 100.00,
 "weight": 10.00,
 "status": "published",
 "createdBy": 5,
 "createdAt": "2026-04-01T08:00:00Z",
 "updatedAt": "2026-04-01T08:00:00Z",
 "course": { /* course object */ },
 "instructions": [
 {
 "id": 1, // number — Instruction ID
 "labId": 1, // number
 "fileId": null, // number | null — FK to files
 "instructionText": "Step 1: Create a new Python file", // string | null
 "orderIndex": 1, // number — Sort order
 "createdAt": "2026-04-01T08:00:00Z"
 }
 ]
}
```
---
### 7.3 Create Lab
```
POST /api/labs
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Request Body
| Field | Type | Required | Default | Constraints | Description |
|---|---|---|---|---|---|
| `courseId` | `integer` | ✅ | — | Must exist | Course ID |
| `title` | `string` | ✅ | — | — | Lab title |
| `description` | `string` | ❌ | `null` | — | Lab description |
| `labNumber` | `integer` | ❌ | `null` | — | Lab sequence number |
| `dueDate` | `string` | ❌ | `null` | ISO 8601 | Due date |
| `availableFrom` | `string` | ❌ | `null` | ISO 8601 | Available from date |
| `maxScore` | `number` | ❌ | `100` | — | Maximum score |
| `weight` | `number` | ❌ | `0` | — | Weight in final grade |
| `status` | `string` | ❌ | `draft` | `LabStatus` enum | Initial status |
#### Example Request
```json
{
 "courseId": 1,
 "title": "Binary Search Lab",
 "description": "Implement binary search in Python",
 "labNumber": 1,
 "dueDate": "2026-04-15T23:59:59Z",
 "availableFrom": "2026-04-01T00:00:00Z",
 "maxScore": 100,
 "weight": 10,
 "status": "draft"
}
```
#### Response `201 Created`
Returns the created lab object.
---
### 7.4 Update Lab
```
PUT /api/labs/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> **Note**: This endpoint uses **PUT** (full replacement), but since `UpdateLabDto extends PartialType(CreateLabDto)`, all fields are optional.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Request Body
All fields from `CreateLabDto` are **optional** (uses `PartialType`).
#### Response `200 OK`
Returns the updated lab object.
---
### 7.5 Delete Lab
```
DELETE /api/labs/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`, `it_admin`
> **Note**: TAs **cannot** delete labs.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `204 No Content`
Empty body.
---
### 7.6 Change Lab Status
```
PATCH /api/labs/:id/status
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `status` | `string` | ✅ | One of: `draft`, `published`, `closed`, `archived` |
> **Note**: Unlike assignments, lab status changes do **not** enforce strict one-way transitions. Any valid status value can be set.
#### Response `200 OK`
Returns the updated lab object (full Lab entity with relations).
---
### 7.7 Get Lab Instructions
```
GET /api/labs/:id/instructions
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `200 OK`
```json
[
 {
 "id": 1, // number — Instruction ID
 "labId": 1, // number — FK to labs
 "fileId": null, // number | null — FK to files table
 "instructionText": "Step 1...", // string | null — Markdown text
 "orderIndex": 1, // number — Sort order (ascending)
 "createdAt": "2026-04-01T08:00:00Z"
 },
 {
 "id": 2,
 "labId": 1,
 "fileId": 5,
 "instructionText": "See attached PDF",
 "orderIndex": 2,
 "createdAt": "2026-04-01T08:05:00Z"
 }
]
```
---
### 7.8 Add Instruction to Lab
```
POST /api/labs/:id/instructions
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `instructionText` | `string` | ❌ | `null` | Instruction content (supports markdown) |
| `fileId` | `integer` | ❌ | `null` | FK to files table for attachment |
| `orderIndex` | `integer` | ❌ | `0` | Sort order |
#### Example Request
```json
{
 "instructionText": "Step 1: Create a new Python file called `binary_search.py`",
 "orderIndex": 1
}
```
#### Response `201 Created`
Returns the created instruction object.
---
### 7.9 Submit Lab Work (Student)
```
POST /api/labs/:id/submit
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `submissionText` | `string` | ❌ | Text/code submission content |
| `fileId` | `integer` | ❌ | File ID from files module |
#### Example Request
```json
{
 "submissionText": "def binary_search(arr, target):\n ...",
 "fileId": 10
}
```
#### Response `201 Created`
```json
{
 "id": 5, // number — Submission ID
 "labId": 1, // number
 "userId": 57, // number — From JWT
 "submissionText": "def binary...", // string | null
 "fileId": 10, // number | null
 "submittedAt": "2026-04-10T14:30:00Z",
 "isLate": false, // boolean — Auto-detected
 "status": "submitted", // string — LabSubmissionStatus
 "score": null, // number | null
 "feedback": null, // string | null
 "gradedBy": null, // number | null
 "gradedAt": null // string | null
}
```
#### Business Rules
- Auto-detects late submission based on `lab.dueDate`
- Sets `isLate = true` if current time > dueDate
---
### 7.10 List Lab Submissions (Instructor/TA/Admin)
```
GET /api/labs/:id/submissions
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `200 OK`
```json
[
 {
 "id": 5,
 "labId": 1,
 "userId": 57,
 "submissionText": "My solution...",
 "fileId": 10,
 "submittedAt": "2026-04-10T14:30:00Z",
 "isLate": false,
 "status": "submitted",
 "score": null,
 "feedback": null,
 "gradedBy": null,
 "gradedAt": null,
 "user": {
 "user_id": 57,
 "first_name": "John",
 "last_name": "Doe",
 "email": "john@example.com"
 },
 "file": {
 "file_id": 10,
 "file_name": "solution.py",
 "file_path": "/uploads/...",
 "mime_type": "text/x-python"
 }
 }
]
```
> Sorted by `submittedAt` DESC.
---
### 7.11 Get My Lab Submission (Student)
```
GET /api/labs/:id/submissions/my
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `200 OK`
Returns an **array** of the student's submissions for this lab (may have multiple), sorted by `submittedAt` DESC. Includes `user` and `file` relations.
```json
[
 {
 "id": 5,
 "labId": 1,
 "userId": 57,
 "submissionText": "...",
 "fileId": 10,
 "submittedAt": "2026-04-10T14:30:00Z",
 "isLate": false,
 "status": "graded",
 "score": 90.00,
 "feedback": "Great work!",
 "gradedBy": 5,
 "gradedAt": "2026-04-12T10:00:00Z",
 "user": { /* student info */ },
 "file": { /* file info or null */ }
 }
]
```
> **Note**: Unlike assignments (which returns the latest single submission), labs returns **all** submissions as an array.
---
### 7.12 Grade Lab Submission
```
PATCH /api/labs/:id/submissions/:subId/grade
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
| `subId` | `integer` | ✅ | Submission ID |
#### Request Body
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `status` | `string` | ✅ | One of: `submitted`, `graded`, `returned`, `resubmit` | Submission status |
| `score` | `number` | ❌ | >= 0 | Score to assign |
| `feedback` | `string` | ❌ | — | Feedback for student |
#### Example Request
```json
{
 "status": "graded",
 "score": 85,
 "feedback": "Good work! Consider optimizing your code for better performance."
}
```
#### Response `200 OK`
Returns the updated submission object with `user`, `file`, and `grader` relations:
```json
{
 "id": 5,
 "labId": 1,
 "userId": 57,
 "submissionText": "...",
 "fileId": 10,
 "submittedAt": "2026-04-10T14:30:00Z",
 "isLate": false,
 "status": "graded",
 "score": 85.00,
 "feedback": "Good work!...",
 "gradedBy": 5,
 "gradedAt": "2026-04-12T10:00:00Z",
 "user": { /* student info */ },
 "file": { /* file info or null */ },
 "grader": {
 "user_id": 5,
 "first_name": "Prof. Smith",
 "last_name": "Smith",
 "email": "smith@example.com"
 }
}
```
> **Side effect**: When `status = 'graded'` and `score` is provided, automatically creates a grade record in the central `grades` table with `gradeType = 'lab'`, `isPublished = true`.
---
### 7.13 Mark Lab Attendance
```
POST /api/labs/:id/attendance
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | `integer` | ✅ | Student user ID to mark |
| `attendanceStatus` | `string` | ✅ | One of: `present`, `absent`, `excused`, `late` |
| `notes` | `string` | ❌ | Additional notes |
#### Example Request
```json
{
 "userId": 57,
 "attendanceStatus": "present",
 "notes": "Arrived on time"
}
```
#### Response `201 Created`
```json
{
 "id": 10, // number — Attendance record ID
 "labId": 1, // number
 "userId": 57, // number
 "attendanceStatus": "present", // string — LabAttendanceStatus
 "checkInTime": "2026-04-10T09:00:00Z", // string | null — Auto-set for present/late
 "notes": "Arrived on time", // string | null
 "markedBy": 5, // number — User who marked (from JWT)
 "createdAt": "2026-04-10T09:00:00Z"
}
```
#### Business Rules
- If a record already exists for this student+lab, it **updates** the existing record
- `checkInTime` is automatically set when status is `present` or `late`
---
### 7.14 Get Lab Attendance
```
GET /api/labs/:id/attendance
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Response `200 OK`
```json
[
 {
 "id": 10,
 "labId": 1,
 "userId": 57,
 "attendanceStatus": "present",
 "checkInTime": "2026-04-10T09:00:00Z",
 "notes": "Arrived on time",
 "markedBy": 5,
 "createdAt": "2026-04-10T09:00:00Z"
 }
]
```
> Sorted by `createdAt` ASC.
---
### 7.15 Upload Lab Instruction (Google Drive)
```
POST /api/labs/:id/instructions/upload
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
**Content-Type**: `multipart/form-data`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `file` | `binary` | ✅ | PDF, DOCX, etc. | Instruction file |
| `title` | `string` | ❌ | Max 255 chars | Instruction title |
| `orderIndex` | `integer` | ❌ | >= 0, default `0` | Sort order |
#### Response `201 Created`
```json
{
 "instruction": {
 "id": 3,
 "labId": 1,
 "instructionText": "Lab 1 - Getting Started Guide",
 "orderIndex": 1,
 "createdAt": "2026-04-01T08:00:00Z"
 },
 "driveFile": {
 "driveId": "1abc...",
 "fileName": "Lab_1_-_Getting_Started_Guide_v1.pdf",
 "webViewLink": "https://drive.google.com/file/d/1abc.../view",
 "webContentLink": "https://drive.google.com/uc?id=1abc..."
 }
}
```
---
### 7.16 Upload TA Material (Google Drive)
```
POST /api/labs/:id/ta-materials/upload
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
**Content-Type**: `multipart/form-data`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `file` | `binary` | ✅ | — | TA material file |
| `title` | `string` | ❌ | Max 255 chars | Material title |
| `materialType` | `string` | ❌ | One of: `answer_key`, `grading_rubric`, `solution`, `notes` | Type of TA material |
#### Response `201 Created`
```json
{
 "driveFile": {
 "driveFileId": 125,
 "driveId": "1ghi...",
 "fileName": "solution_Lab_1_Answer_Key.pdf",
 "webViewLink": "https://drive.google.com/file/d/1ghi.../view",
 "webContentLink": "https://drive.google.com/uc?id=1ghi..."
 }
}
```
---
### 7.17 Upload Lab Submission (Google Drive — Student)
```
POST /api/labs/:id/submissions/upload
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
**Content-Type**: `multipart/form-data`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Lab ID |
#### Form Data Fields
| Field | Type | Required | Description |
|---|---|---|---|
| `file` | `binary` | ✅ | Submission file |
| `submissionText` | `string` | ❌ | Notes/comments |
#### Response `201 Created`
```json
{
 "submission": {
 "id": 6,
 "labId": 1,
 "userId": 57,
 "submissionText": "My implementation uses iterative approach",
 "submittedAt": "2026-04-10T14:30:00Z",
 "isLate": false,
 "status": "submitted",
 "score": null,
 "feedback": null,
 "gradedBy": null,
 "gradedAt": null
 },
 "driveFile": {
 "driveFileId": 126,
 "driveId": "1jkl...",
 "fileName": "Lab1_Submission_20260410.py",
 "webViewLink": "https://drive.google.com/file/d/1jkl.../view",
 "webContentLink": "https://drive.google.com/uc?id=1jkl..."
 },
 "isLate": false
}
```
#### Business Rules
- If a submission already exists for this student+lab, the existing record is **updated** (not duplicated)
- Auto-detects `isLate` based on `lab.dueDate`
---
## 8. Role-Based Access Matrix
### 8.1 Courses
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/courses` (list) | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `GET /api/courses/:id` (details) | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `GET /api/courses/department/:deptId` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `POST /api/courses` (create) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `PATCH /api/courses/:id` (update) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `DELETE /api/courses/:id` (delete) | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| `GET /api/courses/:id/prerequisites` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `POST /api/courses/:id/prerequisites` | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
| `DELETE /api/courses/:id/prerequisites/:id` | ❌ | ❌ | ❌ | ✅ | ✅ | ❌ |
### 8.2 Course Sections
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/sections/course/:courseId` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `GET /api/sections/:id` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `POST /api/sections` (create) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `PATCH /api/sections/:id` (update) | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `PATCH /api/sections/:id/enrollment` | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
### 8.3 Course Schedules
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/schedules/section/:sectionId` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `GET /api/schedules/:id` | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public | ✅ Public |
| `POST /api/schedules/section/:sectionId` | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
| `DELETE /api/schedules/:id` | ❌ | ✅ | ❌ | ✅ | ✅ | ❌ |
### 8.4 Assignments
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/assignments` (list) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `GET /api/assignments/:id` (details) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /api/assignments` (create) | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `PATCH /api/assignments/:id` (update) | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `DELETE /api/assignments/:id` (delete) | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `PATCH /api/assignments/:id/status` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `POST /api/assignments/:id/submit` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `GET /api/assignments/:id/submissions/my` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `GET /api/assignments/:id/submissions` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `PATCH /:id/submissions/:subId/grade` | ❌ | ✅ | ✅ | ❌ | ❌ | ❌ |
| `POST /:id/instructions/upload` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `POST /:id/submissions/upload` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
### 8.5 Labs
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/labs` (list) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `GET /api/labs/:id` (details) | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /api/labs` (create) | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `PUT /api/labs/:id` (update) | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `DELETE /api/labs/:id` (delete) | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `PATCH /api/labs/:id/status` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `GET /api/labs/:id/instructions` | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /api/labs/:id/instructions` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /api/labs/:id/submit` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `GET /api/labs/:id/submissions` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `GET /api/labs/:id/submissions/my` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `PATCH /:id/submissions/:subId/grade` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /api/labs/:id/attendance` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `GET /api/labs/:id/attendance` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /:id/instructions/upload` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /:id/ta-materials/upload` | ❌ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `POST /:id/submissions/upload` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
### 8.6 Enrollments
| Endpoint | Student | Instructor | TA | Admin | IT Admin | Dept Head |
|---|:---:|:---:|:---:|:---:|:---:|:---:|
| `GET /api/enrollments/my-courses` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `GET /api/enrollments/available` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `POST /api/enrollments/register` | ✅ | ❌ | ❌ | ❌ | ❌ | ❌ |
| `DELETE /api/enrollments/:id` | ✅ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `GET /api/enrollments/teaching` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `GET /api/enrollments/periods` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `GET /api/sections/:sectionId/students` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `GET /api/sections/:sectionId/waitlist` | ❌ | ✅ | ❌ | ✅ | ❌ | ❌ |
| `POST /api/enrollments/sections/:sectionId/instructors` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `DELETE /api/enrollments/sections/:sectionId/instructors/:id` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `GET /api/enrollments/sections/:sectionId/instructors` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
| `POST /api/enrollments/sections/:sectionId/tas` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `DELETE /api/enrollments/sections/:sectionId/tas/:id` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `GET /api/enrollments/sections/:sectionId/tas` | ❌ | ✅ | ✅ | ✅ | ❌ | ❌ |
> **Note**: `department_head` role currently has **NO access** to courses/assignments/labs features. This role only has access to schedule templates and campus events.
---
## 9. Course Enrollment Module
**Base Path**: `/api/enrollments`
> **All endpoints require JWT authentication** (`@UseGuards(JwtAuthGuard, RolesGuard)`).
> This module handles student enrollment in courses, including registration, dropping, available courses with prerequisites validation, and instructor/TA assignment to sections.
### 9.0 Enrollment Enums
#### EnrollmentStatus
| Value | Description |
|---|---|
| `enrolled` | Student is actively enrolled in the section |
| `waitlisted` | Student is on the waitlist (not currently implemented) |
| `dropped` | Student has dropped/withdrawn from the section |
| `completed` | Student has completed the course with a grade |
| `failed` | Student failed the course |
#### DropReason
| Value | Description |
|---|---|
| `student_request` | Student voluntarily dropped |
| `administrative` | Admin-initiated drop |
| `academic` | Academic reasons (e.g., failed prerequisite) |
| `schedule_conflict` | Schedule conflict detected |
### 9.0.1 Database Entity
#### `course_enrollments` Table
| Column | DB Type | TS Type | Nullable | Default | Description |
|---|---|---|---|---|---|
| `enrollment_id` | `bigint unsigned` | `number` | ❌ (PK) | Auto | Primary key |
| `user_id` | `bigint unsigned` | `number` | ❌ | — | FK → `users` (student) |
| `section_id` | `bigint unsigned` | `number` | ❌ | — | FK → `course_sections` |
| `program_id` | `bigint unsigned` | `number \| null` | ✅ | `null` | FK → `programs` |
| `enrollment_status` | `enum('enrolled','waitlisted','dropped','completed','failed')` | `EnrollmentStatus` | ❌ | `'enrolled'` | Enrollment status |
| `grade` | `varchar(5)` | `string \| null` | ✅ | `null` | Letter grade (A, A-, B+, etc.) |
| `final_score` | `decimal(5,2)` | `number \| null` | ✅ | `null` | Final numeric score |
| `enrollment_date` | `datetime` | `Date` | ❌ | Auto | When student enrolled |
| `dropped_at` | `datetime` | `Date \| null` | ✅ | `null` | When student dropped |
| `completed_at` | `datetime` | `Date \| null` | ✅ | `null` | When course was completed |
| `updated_at` | `timestamp` | `Date` | ❌ | Auto | Last update timestamp |
**Indexes**: `(user_id, status)`, `(section_id, status)`, unique constraint on `(user_id, section_id)`
---
### 9.1 Get My Enrolled Courses (Student)
```
GET /api/enrollments/my-courses
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `semester` | `integer` | ❌ | — | Filter by semester ID |
#### Response `200 OK`
```json
[
 {
 "id": 1, // number — Enrollment ID
 "userId": 57, // number — Student user ID
 "sectionId": 11, // number — Section ID
 "status": "enrolled", // string — EnrollmentStatus enum
 "grade": null, // string | null — Letter grade
 "finalScore": null, // number | null — Final numeric score
 "enrollmentDate": "2025-09-01T10:00:00Z", // string — ISO 8601
 "droppedAt": null, // string | null
 "completedAt": null, // string | null
 "updatedAt": "2025-09-01T10:00:00Z", // string — ISO 8601
 "canDrop": true, // boolean — Whether student can still drop
 "dropDeadline": "2025-10-15T23:59:59Z", // string | null — Drop deadline
 "course": {
 "id": 1,
 "name": "Introduction to CS",
 "code": "CS101",
 "description": "...",
 "credits": 3,
 "level": "FRESHMAN"
 },
 "section": {
 "id": 11,
 "sectionNumber": "1",
 "maxCapacity": 30,
 "currentEnrollment": 25,
 "location": "Room A101",
 "status": "OPEN"
 },
 "semester": {
 "id": 1,
 "name": "Fall 2025",
 "startDate": "2025-09-01",
 "endDate": "2025-12-15"
 },
 "instructor": null, // object | null — Currently disabled
 "prerequisites": [ // array — Prerequisites with completion status
 {
 "id": 1,
 "courseId": 1,
 "prerequisiteCourseId": 2,
 "courseCode": "CS100",
 "courseName": "Programming Basics",
 "isMandatory": true,
 "studentCompleted": true,
 "studentGrade": "A"
 }
 ]
 }
]
```
---
### 9.2 Get Available Courses (Student)
```
GET /api/enrollments/available
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
> Returns courses the student **can enroll in**, checking:
> - Prerequisites completed with grade **B- or higher**
> - Section has available seats
> - No schedule conflicts with current enrollments
> - Course is active and not cancelled
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `departmentId` | `integer` | ❌ | — | Filter by department |
| `semesterId` | `integer` | ❌ | — | Filter by semester |
| `search` | `string` | ❌ | — | Search in course name/code |
| `level` | `string` | ❌ | — | Filter by course level |
| `page` | `integer` | ❌ | `1` | Page number |
| `limit` | `integer` | ❌ | `20` | Items per page |
#### Response `200 OK`
```json
[
 {
 "id": 1, // number — Course ID
 "name": "Introduction to CS", // string
 "code": "CS101", // string
 "description": "...", // string | null
 "credits": 3, // number
 "level": "FRESHMAN", // string — CourseLevel enum
 "departmentId": 3, // number
 "departmentName": "Computer Science", // string
 "sections": [ // array — Available sections
 {
 "id": 11,
 "sectionNumber": "1",
 "maxCapacity": 30,
 "currentEnrollment": 25,
 "availableSeats": 5,
 "location": "Room A101",
 "semesterId": 1,
 "semesterName": "Fall 2025"
 }
 ],
 "prerequisites": [ // array — Required prerequisites
 {
 "id": 1,
 "courseId": 1,
 "prerequisiteCourseId": 2,
 "courseCode": "CS100",
 "courseName": "Programming Basics",
 "isMandatory": true
 }
 ],
 "canEnroll": true, // boolean — Whether student meets all requirements
 "enrollmentStatus": null // string | null — Current enrollment status if already enrolled
 }
]
```
---
### 9.3 Enroll in a Course (Student)
```
POST /api/enrollments/register
```
**Auth Required**: ✅ Yes
**Roles**: `student` only
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `number` | ✅ | Section ID to enroll in |
#### Example Request
```json
{
 "sectionId": 11
}
```
#### Response `201 Created`
Returns enrollment response object (same shape as items in 9.1 response).
#### Business Rules & Validation
1. **Already Enrolled**: Cannot enroll if already enrolled in the same section (throws `409`)
2. **Prerequisites**: All prerequisites must be completed with grade **B- or higher**
3. **Schedule Conflicts**: No time overlap with current enrollments in the same semester
4. **Capacity**: If section is full, student is still enrolled (waitlist not implemented)
5. **Retake Logic**:
 - If previously **failed** (grade F): Can retake freely
 - If previously **passed** with B- or better and wants to improve: Requires **admin approval** (throws `400` with `RetakeRequiresAdminApprovalException`)
#### Error Responses
| Status | Description |
|---|---|
| `400` | Prerequisites not met / Schedule conflict / User or section not found |
| `409` | Already enrolled in this section |
---
### 9.4 Drop/Withdraw from a Course
```
DELETE /api/enrollments/:id
```
**Auth Required**: ✅ Yes
**Roles**: `student` (own enrollments), `admin` (any enrollment)
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `id` | `integer` | ✅ | Enrollment ID |
#### Request Body (Optional)
| Field | Type | Required | Description |
|---|---|---|---|
| `reason` | `string` | ❌ | Drop reason from `DropReason` enum |
#### Response `200 OK`
Returns the updated enrollment object with `status: "dropped"` and `droppedAt` timestamp.
#### Business Rules
1. **Permission**: Students can only drop their own enrollments; admins can drop any
2. **Drop Deadline**: Students can only drop before **50% of semester has elapsed** (admins can override)
3. **Status Changes**: Enrollment status changes from `enrolled` → `dropped`
4. **Section Count**: Section's `currentEnrollment` is decremented
#### Error Responses
| Status | Description |
|---|---|
| `400` | Drop deadline passed / Cannot drop past enrollment |
| `403` | Forbidden — not your enrollment |
| `404` | Enrollment not found |
---
### 9.5 Get Teaching Courses (Instructor/TA)
```
GET /api/enrollments/teaching
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`
> Returns all course sections where the user is assigned as an instructor or TA.
#### Response `200 OK`
```json
[
 {
 "sectionId": 11,
 "courseId": 1,
 "course": {
 "id": 1,
 "name": "Introduction to CS",
 "code": "CS101",
 "description": "...",
 "credits": 3,
 "level": "FRESHMAN"
 },
 "section": {
 "id": 11,
 "sectionNumber": "1",
 "maxCapacity": 30,
 "currentEnrollment": 25,
 "location": "Room A101"
 },
 "semester": {
 "id": 1,
 "name": "Fall 2025",
 "startDate": "2025-09-01",
 "endDate": "2025-12-15"
 }
 }
]
```
---
### 9.6 Get Section Students
```
GET /api/sections/:sectionId/students
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`
> Returns all **actively enrolled** students (status = `enrolled`) in a section.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
Returns array of enrollment objects (same shape as 9.1), sorted by `enrollmentDate ASC`.
---
### 9.7 Get Section Waitlist
```
GET /api/sections/:sectionId/waitlist
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`
> **Currently Not Implemented**: Returns empty array. Waitlist functionality requires a separate waitlist table.
#### Response `200 OK`
```json
[]
```
---
### 9.8 Assign Instructor to Section (Admin)
```
POST /api/enrollments/sections/:sectionId/instructors
```
**Auth Required**: ✅ Yes
**Roles**: `admin` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Request Body
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| `userId` | `number` | ✅ | — | User ID of instructor (must have `instructor` role) |
| `role` | `string` | ❌ | `primary` | One of: `primary`, `co_instructor`, `guest` |
| `responsibilities` | `string` | ❌ | — | Free-text description |
#### Example Request
```json
{
 "userId": 58,
 "role": "primary",
 "responsibilities": "Lead lectures, grade assignments"
}
```
#### Response `201 Created`
```json
{
 "id": 1, // number — Instructor assignment ID
 "sectionId": 11,
 "userId": 58,
 "role": "primary",
 "responsibilities": "Lead lectures, grade assignments",
 "assignedAt": "2025-09-01T10:00:00Z",
 "user": {
 "userId": 58,
 "firstName": "Tarek",
 "lastName": "Instructor",
 "email": "tarek@example.com"
 }
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid user ID or section ID |
| `404` | Section or user not found |
| `409` | Instructor already assigned to this section |
---
### 9.9 Get Section Instructors
```
GET /api/enrollments/sections/:sectionId/instructors
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `instructor`, `teaching_assistant`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
Returns array of instructor assignment objects (same shape as 9.8 response).
---
### 9.10 Remove Instructor from Section (Admin)
```
DELETE /api/enrollments/sections/:sectionId/instructors/:assignmentId
```
**Auth Required**: ✅ Yes
**Roles**: `admin` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
| `assignmentId` | `integer` | ✅ | Instructor assignment ID |
#### Response `204 No Content`
Empty body.
---
### 9.11 Assign TA to Section (Admin)
```
POST /api/enrollments/sections/:sectionId/tas
```
**Auth Required**: ✅ Yes
**Roles**: `admin` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| `userId` | `number` | ✅ | User ID of TA (must have `teaching_assistant` role) |
| `responsibilities` | `string` | ❌ | Free-text description (e.g., "Grading labs, office hours Mon/Wed") |
#### Example Request
```json
{
 "userId": 60,
 "responsibilities": "Grade lab submissions, hold office hours on Tuesday"
}
```
#### Response `201 Created`
```json
{
 "id": 2, // number — TA assignment ID
 "sectionId": 11,
 "userId": 60,
 "responsibilities": "Grade lab submissions, hold office hours on Tuesday",
 "assignedAt": "2025-09-01T10:00:00Z",
 "user": {
 "userId": 60,
 "firstName": "John",
 "lastName": "TA",
 "email": "ta@example.com"
 }
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid user ID or section ID |
| `404` | Section or user not found |
| `409` | TA already assigned to this section |
---
### 9.12 Get Section TAs
```
GET /api/enrollments/sections/:sectionId/tas
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `instructor`, `teaching_assistant`
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
Returns array of TA assignment objects (same shape as 9.11 response).
---
### 9.13 Remove TA from Section (Admin)
```
DELETE /api/enrollments/sections/:sectionId/tas/:assignmentId
```
**Auth Required**: ✅ Yes
**Roles**: `admin` only
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
| `assignmentId` | `integer` | ✅ | TA assignment ID |
#### Response `204 No Content`
Empty body.
---
### 9.14 Get Section Instructor Summary
```
GET /api/enrollments/section/:sectionId/instructor
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `instructor`, `teaching_assistant`, `student`
> Returns simplified instructor info for a section.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
```json
{
 "instructorId": 58,
 "instructor": {
 "userId": 58,
 "fullName": "Tarek Instructor",
 "email": "tarek@example.com"
 }
}
```
---
### 9.15 Get Section TA Summaries
```
GET /api/enrollments/section/:sectionId/tas
```
**Auth Required**: ✅ Yes
**Roles**: `admin`, `instructor`, `teaching_assistant`, `student`
> Returns simplified TA info for a section.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `sectionId` | `integer` | ✅ | Section ID |
#### Response `200 OK`
```json
[
 {
 "userId": 60,
 "fullName": "Tarek TA",
 "email": "ta@example.com"
 }
]
```
---
### 9.16 Get Enrollment Periods
```
GET /api/enrollments/periods
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
> Returns semesters with registration date ranges.
#### Response `200 OK`
```json
[
 {
 "id": 1,
 "semesterName": "Fall 2025",
 "semesterCode": "FA25",
 "registrationStart": "2025-08-01T00:00:00Z",
 "registrationEnd": "2025-08-25T23:59:59Z",
 "semesterStart": "2025-09-01T00:00:00Z",
 "semesterEnd": "2025-12-15T23:59:59Z",
 "status": "active"
 }
]
```
---
## 10. Error Handling
### 9.1 Standard Error Response Shape
```json
{
 "statusCode": 404,
 "message": "Assignment not found",
 "error": "Not Found"
}
```
Or for validation errors (`400`):
```json
{
 "statusCode": 400,
 "message": [
 "courseId must be a number",
 "title must be longer than or equal to 3 characters"
 ],
 "error": "Bad Request"
}
```
### 9.2 Common Error Codes
| Status | When |
|---|---|
| `400` | Validation failure, invalid state transition, business rule violation |
| `401` | Missing or invalid JWT token |
| `403` | Insufficient role permissions |
| `404` | Resource not found |
| `409` | Duplicate resource (e.g., course code) |
### 9.3 Business Rule Errors (400)
| Module | Error | Description |
|---|---|---|
| Courses | Course code exists | `CourseCodeAlreadyExistsException` — code+department must be unique |
| Courses | Circular prerequisite | `CircularPrerequisiteDetectedException` — detected via DFS |
| Courses | Delete with sections | `CannotDeleteCourseWithActiveSectionsException` |
| Assignments | Not published | `AssignmentNotPublishedException` — must be `published` to submit |
| Assignments | Not available yet | `AssignmentNotAvailableYetException` — before `availableFrom` |
| Assignments | Deadline passed | `SubmissionDeadlinePassedException` — past `dueDate` and late not allowed |
| Assignments | Not enrolled | Student not enrolled in the course |
| Assignments | Invalid transition | Status transition not allowed (e.g., `draft` to `closed`) |
| Sections | Section full | `SectionFullException` — enrollment exceeds capacity |
| Sections | Capacity reduction | Cannot reduce capacity below current enrollment |
| Schedules | Invalid time | `InvalidTimeRangeException` — end time <= start time |
| Schedules | Conflict | `ScheduleConflictException` — room/time overlap |
---
## 10. Flutter Integration Tips
### 10.1 HTTP Client Setup
```dart
// Base configuration
const baseUrl = 'http://your-server:3001';
// Auth header
final headers = {
 'Content-Type': 'application/json',
 'Authorization': 'Bearer $accessToken',
};
```
### 10.2 Parsing `lateSubmissionAllowed`
The backend stores this as a MySQL `TINYINT(1)` — it comes back as `0` or `1` (number), not `true`/`false`:
```dart
final isLateAllowed = (assignment['lateSubmissionAllowed'] as num) == 1;
```
### 10.3 Parsing `allowedFileTypes`
This field is a **JSON string** (not an array). Parse it:
```dart
final List<String> fileTypes = assignment['allowedFileTypes'] != null
 ? List<String>.from(jsonDecode(assignment['allowedFileTypes']))
 : [];
```
### 10.4 Decimal Fields
`maxScore`, `weight`, `latePenaltyPercent`, `score` come back as decimal numbers (may be strings from some DB drivers). Always parse:
```dart
final maxScore = double.tryParse(assignment['maxScore'].toString()) ?? 100.0;
```
### 10.5 File Uploads (multipart/form-data)
Use `dio` or `http.MultipartRequest`:
```dart
// Using Dio
final formData = FormData.fromMap({
 'file': await MultipartFile.fromFile(filePath, filename: fileName),
 'title': 'My submission',
 'submissionText': 'Notes here',
});
final response = await dio.post(
 '$baseUrl/api/assignments/3/submissions/upload',
 data: formData,
 options: Options(headers: {'Authorization': 'Bearer $token'}),
);
```
### 10.6 Pagination Helper
```dart
class PaginatedResponse<T> {
 final List<T> data;
 final int total;
 final int page;
 final int limit;
 final int totalPages;
 bool get hasNextPage => page < totalPages;
 bool get hasPreviousPage => page > 1;
}
```
### 10.7 Enum Mapping
```dart
enum AssignmentStatus { draft, published, closed, archived }
extension AssignmentStatusExt on AssignmentStatus {
 String get value => name; // 'draft', 'published', etc.
 static AssignmentStatus fromString(String s) =>
 AssignmentStatus.values.firstWhere((e) => e.name == s);
}
```
### 10.8 Date Handling
All dates are ISO 8601 strings. Parse with:
```dart
final dueDate = DateTime.parse(assignment['dueDate']); // UTC
final localDueDate = dueDate.toLocal(); // Convert to local timezone
```
### 10.9 Role-Based UI
```dart
// Show/hide actions based on role
final userRoles = currentUser.roles; // List<String>
final canCreateAssignment = userRoles.any(
 (r) => ['instructor', 'admin'].contains(r),
);
final canSubmit = userRoles.contains('student');
final canGrade = userRoles.any(
 (r) => ['instructor', 'teaching_assistant'].contains(r),
);
```
### 10.10 Handling `isLate` Differences
| Module | `isLate` Type | Values |
|---|---|---|
| Assignments | `number` (tinyint) | `0` = on-time, `1` = late |
| Labs | `boolean` | `true` / `false` |
```dart
// Assignments
final isLate = (submission['isLate'] as num) == 1;
// Labs
final isLate = submission['isLate'] as bool;
```
---
## 11. Course Materials & Video Lectures Module
**Base Path**: `/api/courses/:courseId/materials`
> **All endpoints require JWT authentication** (`@UseGuards(JwtAuthGuard, RolesGuard)`).
> This module handles uploading, viewing, organizing, and managing all course materials — including **video lectures** uploaded to YouTube and **documents** stored on Google Drive.
### 11.0 Enums Reference (Course Materials)
#### MaterialType
| Value | Description |
|---|---|
| `lecture` | Lecture content (notes, handouts) |
| `slide` | Presentation slides |
| `video` | Video content (YouTube integration) |
| `reading` | Reading material |
| `link` | External link |
| `document` | Generic document |
| `other` | Uncategorized material |
#### OrganizationType (for Course Structure)
| Value | Description |
|---|---|
| `lecture` | Main lecture content |
| `section` | Discussion or tutorial section |
| `lab` | Hands-on lab session |
| `tutorial` | Tutorial session |
### 11.0.1 Database Entities
#### `course_materials` Table
| Column | DB Type | TS Type | Nullable | Default | Description |
|---|---|---|---|---|---|
| `material_id` | `bigint unsigned` | `number` | ❌ (PK) | Auto | Primary key |
| `course_id` | `bigint unsigned` | `number` | ❌ | — | FK → `courses` |
| `file_id` | `bigint unsigned` | `number \| null` | ✅ | `null` | FK → `files` (local files) |
| `drive_file_id` | `bigint unsigned` | `number \| null` | ✅ | `null` | FK → `drive_files` (Google Drive) |
| `material_type` | `enum('lecture','slide','video','reading','link','document','other')` | `MaterialType` | ❌ | `'document'` | Type of material |
| `title` | `varchar(255)` | `string` | ❌ | — | Material title |
| `description` | `text` | `string \| null` | ✅ | `null` | Description |
| `external_url` | `varchar(500)` | `string \| null` | ✅ | `null` | External URL (YouTube embed URL, Google Drive link, etc.) |
| `youtube_video_id` | `varchar(50)` | `string \| null` | ✅ | `null` | YouTube video ID (for video materials) |
| `order_index` | `int` | `number` | ❌ | `0` | Sort order within week |
| `week_number` | `int` | `number \| null` | ✅ | `null` | Week number for organizing by course week |
| `view_count` | `int` | `number` | ❌ | `0` | Number of times viewed |
| `download_count` | `int` | `number` | ❌ | `0` | Number of times downloaded |
| `uploaded_by` | `bigint unsigned` | `number` | ❌ | — | FK → `users` (creator) |
| `is_published` | `tinyint` | `boolean` | ❌ | `0` | `0` = draft (hidden), `1` = published (visible to students) |
| `published_at` | `timestamp` | `Date \| null` | ✅ | `null` | When material was first published |
| `created_at` | `timestamp` | `Date` | ❌ | Auto | Creation timestamp |
| `updated_at` | `timestamp` | `Date` | ❌ | Auto | Last update timestamp |
**Indexes**: `course_id`, `uploaded_by`, `material_type`, `week_number`
#### `lecture_sections_labs` Table (Course Structure)
| Column | DB Type | TS Type | Nullable | Default | Description |
|---|---|---|---|---|---|
| `organization_id` | `bigint unsigned` | `number` | ❌ (PK) | Auto | Primary key |
| `course_id` | `bigint unsigned` | `number` | ❌ | — | FK → `courses` |
| `material_id` | `bigint unsigned` | `number \| null` | ✅ | `null` | FK → `course_materials` |
| `organization_type` | `enum('lecture','section','lab','tutorial')` | `OrganizationType \| null` | ✅ | `null` | Type of content organization |
| `title` | `varchar(255)` | `string` | ❌ | — | Structure item title |
| `week_number` | `int` | `number \| null` | ✅ | `null` | Week number |
| `order_index` | `int` | `number` | ❌ | `0` | Sort order |
| `description` | `text` | `string \| null` | ✅ | `null` | Description |
| `created_at` | `timestamp` | `Date` | ❌ | Auto | Creation timestamp |
| `updated_at` | `timestamp` | `Date` | ❌ | Auto | Last update timestamp |
**Indexes**: `course_id`, `week_number`
---
### 11.1 List Course Materials
```
GET /api/courses/:courseId/materials
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users (role-based visibility filtering)
#### Role-Based Visibility
| Role | Can See |
|---|---|
| `student` | Only **published** materials (`is_published = 1`) |
| `instructor` | All materials (including drafts) |
| `teaching_assistant` | All materials (including drafts) |
| `admin` / `it_admin` | All materials (including drafts) |
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `materialType` | `string` | ❌ | — | Filter by `MaterialType` enum (`lecture`, `slide`, `video`, `reading`, `link`, `document`, `other`) |
| `weekNumber` | `integer` | ❌ | — | Filter by week number |
| `isPublished` | `boolean` | ❌ | — | Filter by visibility. Only effective for `instructor`, `ta`, `admin` roles. Ignored for students. |
| `search` | `string` | ❌ | — | Search in title and description (partial match / `LIKE`) |
| `sortBy` | `string` | ❌ | `orderIndex` | Sort field: `createdAt`, `title`, `orderIndex` |
| `sortOrder` | `string` | ❌ | `ASC` | Sort order: `ASC` or `DESC` |
| `page` | `integer` | ❌ | `1` | Page number (1-indexed, min: 1) |
| `limit` | `integer` | ❌ | `10` | Items per page (1-100) |
#### Response `200 OK`
```json
{
 "data": [
 {
 "materialId": 1, // number (bigint) — Material ID (PK)
 "courseId": 1, // number — FK to courses
 "fileId": null, // number | null — FK to local files
 "driveFileId": 123, // number | null — FK to drive_files
 "materialType": "video", // string — MaterialType enum
 "title": "Lecture 1: Introduction to DS", // string — Material title (max 255)
 "description": "Covers basics of...", // string | null — Description
 "externalUrl": "https://www.youtube.com/embed/abc123", // string | null — YouTube embed URL or Drive view URL
 "youtubeVideoId": "abc123", // string | null — YouTube video ID
 "orderIndex": 0, // number — Sort position
 "weekNumber": 1, // number | null — Week number
 "viewCount": 42, // number — Times viewed
 "downloadCount": 10, // number — Times downloaded
 "uploadedBy": 5, // number — Creator user ID
 "isPublished": true, // boolean — Visibility state (tinyint 0/1 mapped to boolean)
 "publishedAt": "2025-06-01T10:00:00Z", // string | null — ISO 8601 timestamp
 "createdAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "updatedAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "course": { // object — Joined course relation
 "id": 1,
 "departmentId": 3,
 "name": "Introduction to CS",
 "code": "CS101"
 },
 "file": null, // object | null — Joined local file relation
 "uploader": { // object — Joined uploader user relation
 "user_id": 5,
 "first_name": "Dr. Jane",
 "last_name": "Smith",
 "email": "jane@example.com"
 }
 }
 ],
 "meta": {
 "total": 25, // number — Total matching records
 "page": 1, // number — Current page
 "limit": 10, // number — Items per page
 "totalPages": 3 // number — Total pages
 }
}
```
---
### 11.2 Get Material by ID
```
GET /api/courses/:courseId/materials/:id
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
> **Students** can only view materials where `isPublished = true`. Requesting an unpublished material as a student returns `404 Not Found`.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Response `200 OK`
Returns a single material object (same shape as items in 11.1 `data` array, including `course`, `file`, and `uploader` relations).
#### Error Responses
| Status | Description |
|---|---|
| `401` | Unauthorized — missing or invalid token |
| `404` | Material not found (or unpublished material accessed by student) |
---
### 11.3 Create Course Material
```
POST /api/courses/:courseId/materials
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> **Authorization**: Non-admin users must be **assigned to the course** (as instructor of a section or TA of a section). Unassigned instructors/TAs receive `403 Forbidden`.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `title` | `string` | ✅ | Max 255 chars, non-empty | Material title |
| `materialType` | `string` | ✅ | `MaterialType` enum | Type of material |
| `description` | `string` | ❌ | — | Material description |
| `fileId` | `number` | ❌ | Must reference valid file ID | File ID from the Files module |
| `externalUrl` | `string` | ❌ | Max 500 chars | External URL (YouTube link, external resource, etc.) |
| `orderIndex` | `number` | ❌ | Min 0 | Sort order for display |
| `weekNumber` | `number` | ❌ | Min 1 | Week number for content organization |
| `isPublished` | `boolean` | ❌ | — | Publish immediately (`true`) or save as draft (`false`). **Default: `false`** |
#### Example Request
```json
{
 "title": "Lecture 1: Introduction to Programming",
 "materialType": "video",
 "description": "Introduction to basic programming concepts.",
 "externalUrl": "https://www.youtube.com/watch?v=example",
 "weekNumber": 1,
 "orderIndex": 0,
 "isPublished": false
}
```
#### Response `201 Created`
Returns the created material object (same shape as items in 11.1 response without `course`/`file`/`uploader` relations — raw entity).
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data (validation failure) |
| `403` | Forbidden — user not assigned to this course |
---
### 11.4 Bulk Create Materials
```
POST /api/courses/:courseId/materials/bulk
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> Maximum **50 materials** per request. Non-admin users must be assigned to the course.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `materials` | `CreateMaterialDto[]` | ✅ | 1-50 items, validated individually | Array of material objects (same shape as 11.3 request body) |
#### Example Request
```json
{
 "materials": [
 {
 "title": "Lecture 1: Introduction",
 "materialType": "lecture",
 "description": "Introduction to the course",
 "weekNumber": 1
 },
 {
 "title": "Lecture 2: Fundamentals",
 "materialType": "lecture",
 "description": "Fundamentals of the subject",
 "weekNumber": 1
 }
 ]
}
```
#### Response `201 Created`
```json
{
 "message": "Successfully created 2 materials", // string — Success message
 "count": 2, // number — Count of created items
 "data": [ // CourseMaterial[] — Created material objects
 {
 "materialId": 10,
 "courseId": 1,
 "title": "Lecture 1: Introduction",
 "materialType": "lecture",
 "description": "Introduction to the course",
 "weekNumber": 1,
 "orderIndex": 0,
 "isPublished": false,
 "uploadedBy": 5,
 "createdAt": "2025-06-01T08:00:00Z",
 "updatedAt": "2025-06-01T08:00:00Z"
 }
 ]
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data — minimum 1 material required, maximum 50 allowed |
| `403` | Forbidden — user not assigned to this course |
---
### 11.5 Upload Video Material (YouTube)
```
POST /api/courses/:courseId/materials/video
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
**Content-Type**: `multipart/form-data`
> **This is the primary endpoint for uploading video lectures.**
> The backend uploads the video to YouTube as **unlisted**, then creates a `course_materials` record with the YouTube embed URL and video ID.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `video` | `binary (file)` | ✅ | Formats: `mp4`, `avi`, `mov`, `webm`, `mkv`, `flv`, `wmv` | Video file to upload |
| `title` | `string` | ✅ | Max 255 chars, non-empty | Video title |
| `description` | `string` | ❌ | — | Video description |
| `tags` | `string[]` | ❌ | Array of strings | Tags for the YouTube video |
| `weekNumber` | `integer` | ❌ | 1–52 | Week to assign the video to |
| `orderIndex` | `integer` | ❌ | Min 0, default: `0` | Sort order within the week |
| `isPublished` | `boolean` | ❌ | Default: `false` | Publish immediately or save as draft |
#### Upload Flow (Internal)
1. Backend validates user is authorized for this course
2. Video file buffer is uploaded to **YouTube** (privacy: `unlisted`)
3. YouTube returns `videoId` and URL
4. A `course_materials` record is created with:
 - `materialType` = `video`
 - `externalUrl` = `https://www.youtube.com/embed/{videoId}`
 - `youtubeVideoId` = the YouTube video ID
 - Other metadata (`weekNumber`, `orderIndex`, `isPublished`)
#### Response `201 Created`
```json
{
 "materialId": 1, // number — Created material ID
 "courseId": 1, // number — Course ID
 "title": "Lecture 1: Introduction", // string — Video title
 "materialType": "video", // string — Always "video"
 "description": "This covers the basics...", // string | null
 "externalUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ", // string — YouTube embed URL
 "youtubeVideoId": "dQw4w9WgXcQ", // string — YouTube video ID
 "weekNumber": 1, // number | null
 "orderIndex": 0, // number
 "isPublished": false, // boolean
 "publishedAt": null, // string | null
 "uploadedBy": 5, // number
 "viewCount": 0, // number
 "downloadCount": 0, // number
 "createdAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "updatedAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "youtubeUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", // string — Full YouTube watch URL (appended by service)
 "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ" // string — Embed URL for iframe (appended by service)
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | No video file provided / YouTube upload failed / Invalid input data |
| `403` | Forbidden — user not assigned to this course |
| `413` | Video file too large (YouTube account limits apply) |
---
### 11.6 Upload Document Material (Google Drive)
```
POST /api/courses/:courseId/materials/document
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
**Content-Type**: `multipart/form-data`
> Uploads a document to **Google Drive** in the appropriate course folder hierarchy and creates a material record.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `document` | `binary (file)` | ✅ | Formats: `pdf`, `ppt`, `pptx`, `doc`, `docx`, `xls`, `xlsx`, `txt`, `md`, `zip` | Document file to upload |
| `title` | `string` | ✅ | Max 255 chars, non-empty | Document title |
| `description` | `string` | ❌ | — | Document description |
| `materialType` | `string` | ❌ | `MaterialType` enum, default: `document` | Document type: `lecture`, `slide`, `reading`, `document`, `link` |
| `weekNumber` | `integer` | ❌ | 1–52 | Week to assign the document to |
| `orderIndex` | `integer` | ❌ | Min 0, default: `0` | Sort order within the week |
| `isPublished` | `boolean` | ❌ | Default: `false` | Publish immediately or save as draft |
#### Folder Placement Rules
| `materialType` value | Google Drive folder target |
|---|---|
| `lecture` | `Course/Lectures/` |
| `slide` | `Course/Lectures/` (slides grouped with lectures) |
| `reading` | `Course/General/` |
| `document` | `Course/General/` |
| `link` | `Course/General/` |
| _other_ | `Course/General/` |
#### File Naming Convention
Files are renamed following the pattern:
```
{WeekNN_}{SafeTitle}_v1.{ext}
```
- Example: `Week01_Introduction_to_Data_Structures_v1.pdf`
#### Response `201 Created`
```json
{
 "materialId": 2, // number — Created material ID
 "courseId": 1, // number
 "title": "Week 1 Lecture Notes", // string
 "materialType": "lecture", // string — MaterialType enum
 "description": "Comprehensive lecture notes covering the basics.", // string | null
 "externalUrl": "https://drive.google.com/file/d/abc123/view", // string — Google Drive view URL
 "driveFileId": 123, // number — FK to drive_files table
 "weekNumber": 1, // number | null
 "orderIndex": 0, // number
 "isPublished": false, // boolean
 "publishedAt": null, // string | null
 "uploadedBy": 5, // number
 "createdAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "updatedAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "driveId": "abc123", // string — Google Drive file ID (appended)
 "driveViewUrl": "https://drive.google.com/file/d/abc123/view", // string — View URL (appended)
 "driveDownloadUrl": "https://drive.google.com/uc?id=abc123&export=download", // string — Download URL (appended)
 "fileName": "Week01_Week_1_Lecture_Notes_v1.pdf" // string — Generated file name (appended)
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | No document file / Google Drive upload failed / Invalid input data |
| `403` | Forbidden — user not assigned to this course |
---
### 11.7 Update Material
```
PUT /api/courses/:courseId/materials/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> **Ownership**: Non-admin users can only update materials **they uploaded** (`uploadedBy` must match the requesting user). Admins can update any material.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Request Body (`application/json`) — All fields optional (uses `PartialType` of `CreateMaterialDto`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `title` | `string` | ❌ | Max 255 chars | Updated title |
| `materialType` | `string` | ❌ | `MaterialType` enum | Updated type |
| `description` | `string` | ❌ | — | Updated description |
| `fileId` | `number` | ❌ | Must exist | Updated file reference |
| `externalUrl` | `string` | ❌ | Max 500 chars | Updated external URL |
| `orderIndex` | `number` | ❌ | Min 0 | Updated sort order |
| `weekNumber` | `number` | ❌ | Min 1 | Updated week number |
| `isPublished` | `boolean` | ❌ | — | Updated visibility. If changing from `false` → `true`, `publishedAt` is set automatically. |
#### Response `200 OK`
Returns the updated material object (with `course`, `file`, `uploader` relations).
#### Error Responses
| Status | Description |
|---|---|
| `403` | Forbidden — you can only update materials you uploaded (non-admin) |
| `404` | Material not found |
---
### 11.8 Delete Material
```
DELETE /api/courses/:courseId/materials/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> **Ownership**: Non-admin users can only delete materials **they uploaded**. Admins can delete any material.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Response `200 OK`
```json
{
 "message": "Material deleted successfully" // string
}
```
#### Error Responses
| Status | Description |
|---|---|
| `403` | Forbidden — you can only delete materials you uploaded (non-admin) |
| `404` | Material not found |
---
### 11.9 Toggle Material Visibility
```
PATCH /api/courses/:courseId/materials/:id/visibility
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `teaching_assistant`, `admin`, `it_admin`
> Controls whether a material is visible to students. Non-admin users can only toggle visibility of materials **they uploaded**.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `isPublished` | `boolean` | ✅ | — | `true` = visible to students, `false` = draft (hidden) |
#### Example Request
```json
{
 "isPublished": true
}
```
#### Response `200 OK`
Returns the updated material object (full entity with `course`, `file`, `uploader` relations). `publishedAt` is set to current timestamp on first publish, preserved on subsequent toggles.
#### Error Responses
| Status | Description |
|---|---|
| `403` | Forbidden — you can only change visibility of materials you uploaded (non-admin) |
| `404` | Material not found |
---
### 11.10 Download Material
```
GET /api/courses/:courseId/materials/:id/download
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
> Students can only download **published** materials. Increments `downloadCount` on each successful call.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Response `200 OK`
```json
{
 "material": { // object — Full material entity
 "materialId": 1,
 "title": "Lecture Notes Week 1",
 "materialType": "lecture",
 "fileId": 12,
 "externalUrl": null,
 "viewCount": 42,
 "downloadCount": 11
 // ... full material object fields
 },
 "file": { // object — Associated file entity
 "fileId": 12,
 "fileName": "lecture_notes_w1.pdf",
 "filePath": "/uploads/materials/lecture_notes_w1.pdf",
 "fileSize": 2048576,
 "mimeType": "application/pdf"
 // ... full file object fields
 },
 "downloadUrl": "/uploads/materials/lecture_notes_w1.pdf" // string — Direct download path
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Material does not have a downloadable file (`fileId` is null) |
| `404` | Material or associated file not found |
---
### 11.11 Track Material View
```
POST /api/courses/:courseId/materials/:id/view
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
> Records that a user viewed a material. Increments `viewCount` counter. Used for analytics and engagement tracking.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Request Body
_None_ (empty body)
#### Response `200 OK`
```json
{
 "message": "View tracked successfully", // string
 "materialId": 1, // number — Material ID
 "viewCount": 43 // number — New total view count
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | Material not found |
---
### 11.12 Get Embed URL (Video Materials)
```
GET /api/courses/:courseId/materials/:id/embed
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
> For **video** materials only. Returns the YouTube embed URL and ready-to-use iframe HTML.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Material ID |
#### Response `200 OK` (YouTube video)
```json
{
 "videoId": "dQw4w9WgXcQ", // string — YouTube video ID
 "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ", // string — Embed URL for iframe
 "iframeHtml": "<iframe width=\"560\" height=\"315\" src=\"https://www.youtube.com/embed/dQw4w9WgXcQ\" frameborder=\"0\" allowfullscreen></iframe>" // string — Ready-to-use iframe HTML
}
```
#### Response `200 OK` (Non-YouTube external URL)
```json
{
 "externalUrl": "https://example.com/video.mp4" // string — Raw external URL
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Material is not a video (`materialType !== 'video'`) or has no external URL |
| `404` | Material not found |
---
## 12. Course Structure Module
**Base Path**: `/api/courses/:courseId/structure`
> **All endpoints require JWT authentication** (`@UseGuards(JwtAuthGuard, RolesGuard)`).
> This module provides the organizational layer for course content — mapping materials into weeks, lectures, sections, and labs.
---
### 12.1 Get Course Structure
```
GET /api/courses/:courseId/structure
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Response `200 OK`
```json
{
 "data": [ // LectureSectionLab[] — Flat list of all structure items
 {
 "organizationId": 1, // number — Structure item ID (PK)
 "courseId": 1, // number — FK to courses
 "materialId": 5, // number | null — FK to course_materials
 "organizationType": "lecture", // string | null — OrganizationType enum
 "title": "Week 1: Introduction", // string — Item title
 "weekNumber": 1, // number | null — Week number
 "orderIndex": 0, // number — Sort position
 "description": "Overview of course", // string | null
 "createdAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "updatedAt": "2025-06-01T08:00:00Z", // string — ISO 8601
 "material": { // object | null — Joined material relation
 "materialId": 5,
 "title": "Lecture 1 Slides",
 "materialType": "slide",
 "externalUrl": "https://drive.google.com/...",
 "youtubeVideoId": null,
 "weekNumber": 1,
 "viewCount": 20,
 "isPublished": true
 }
 }
 ],
 "byWeek": { // Record<number, LectureSectionLab[]> — Grouped by week
 "0": [ /* items without a week */ ],
 "1": [ /* week 1 items */ ],
 "2": [ /* week 2 items */ ]
 }
}
```
> **Sorting**: Items sorted by `weekNumber ASC`, then `orderIndex ASC`.
---
### 12.2 Get Structure Item by ID
```
GET /api/courses/:courseId/structure/:id
```
**Auth Required**: ✅ Yes
**Roles**: All authenticated users
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Structure item ID |
#### Response `200 OK`
Returns a single structure item with `course` and `material` relations joined.
```json
{
 "organizationId": 1,
 "courseId": 1,
 "materialId": 5,
 "organizationType": "lecture",
 "title": "Week 1: Introduction",
 "weekNumber": 1,
 "orderIndex": 0,
 "description": "Overview of the course",
 "createdAt": "2025-06-01T08:00:00Z",
 "updatedAt": "2025-06-01T08:00:00Z",
 "course": {
 "id": 1,
 "name": "Introduction to CS",
 "code": "CS101"
 },
 "material": {
 "materialId": 5,
 "title": "Lecture 1 Slides",
 "materialType": "slide"
 }
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | Structure item not found |
---
### 12.3 Create Structure Item
```
POST /api/courses/:courseId/structure
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`, `it_admin`
> **Note**: TAs **cannot** create structure items. Non-admin instructors must be assigned to the course.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `title` | `string` | ✅ | Max 255 chars, non-empty | Structure item title |
| `organizationType` | `string` | ✅ | `OrganizationType` enum (`lecture`, `section`, `lab`, `tutorial`) | Type of content |
| `description` | `string` | ❌ | — | Description of this content section |
| `weekNumber` | `number` | ❌ | Min 1 | Week number for this content |
| `orderIndex` | `number` | ❌ | Min 0. **Auto-calculated** if omitted (max existing + 1 within the week). | Sort order |
| `materialId` | `number` | ❌ | Must reference valid material ID | Link to an existing material |
#### Example Request
```json
{
 "title": "Week 1: Introduction to Data Structures",
 "organizationType": "lecture",
 "description": "Introduction to the course and basic concepts",
 "weekNumber": 1,
 "materialId": 5
}
```
#### Response `201 Created`
Returns the created structure item entity.
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data |
| `403` | Forbidden — only instructors/admins; must be assigned to course |
---
### 12.4 Update Structure Item
```
PUT /api/courses/:courseId/structure/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`, `it_admin`
> All fields from `CreateStructureDto` are optional (`PartialType`). TAs cannot update structure. Non-admin instructors must be assigned to the course.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Structure item ID |
#### Request Body (`application/json`) — All fields optional
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `title` | `string` | ❌ | Max 255 chars | Updated title |
| `organizationType` | `string` | ❌ | `OrganizationType` enum | Updated type |
| `description` | `string` | ❌ | — | Updated description |
| `weekNumber` | `number` | ❌ | Min 1 | Updated week number |
| `orderIndex` | `number` | ❌ | Min 0 | Updated sort order |
| `materialId` | `number` | ❌ | Valid material ID | Updated material link |
#### Response `200 OK`
Returns the updated structure item entity.
#### Error Responses
| Status | Description |
|---|---|
| `403` | Forbidden — only instructors/admins; must be assigned |
| `404` | Structure item not found |
---
### 12.5 Delete Structure Item
```
DELETE /api/courses/:courseId/structure/:id
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`, `it_admin`
> **Important**: Deleting a structure item does **NOT** delete associated materials. The material remains in the `course_materials` table.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
| `id` | `integer` | ✅ | Structure item ID |
#### Response `200 OK`
```json
{
 "message": "Structure item deleted successfully" // string
}
```
#### Error Responses
| Status | Description |
|---|---|
| `403` | Forbidden — only instructors/admins; must be assigned |
| `404` | Structure item not found |
---
### 12.6 Reorder Structure Items
```
PATCH /api/courses/:courseId/structure/reorder
```
**Auth Required**: ✅ Yes
**Roles**: `instructor`, `admin`, `it_admin`
> Reorders multiple structure items in a single request. All IDs must belong to the specified course.
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `courseId` | `integer` | ✅ | Course ID |
#### Request Body (`application/json`)
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `orderIds` | `number[]` | ✅ | Non-empty array of existing structure item IDs | Array of item IDs in the desired new order |
#### Example Request
```json
{
 "orderIds": [3, 1, 2, 4]
}
```
> This would set:
> - ID 3 → `orderIndex: 0`
> - ID 1 → `orderIndex: 1`
> - ID 2 → `orderIndex: 2`
> - ID 4 → `orderIndex: 3`
#### Response `200 OK`
```json
{
 "message": "Structure reordered successfully" // string
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid input data (empty array, non-number values) |
| `403` | Forbidden — only instructors/admins; must be assigned |
| `404` | Some structure items not found or do not belong to this course |
---
## 13. YouTube Integration Module
**Base Path**: `/youtube`
> This module provides **standalone YouTube API integration** for OAuth authentication, video upload, search, and video details retrieval.
> ⚠️ These endpoints are primarily used internally by the Course Materials module (section 11.5) but are also exposed directly for advanced use cases.
---
### 13.1 Get YouTube Auth URL
```
GET /youtube/auth
```
**Auth Required**: ❌ No (Public endpoint)
**Roles**: None
> Returns the Google OAuth2 authorization URL. The user must visit this URL to grant YouTube upload permission.
#### Response `200 OK`
```json
{
 "authUrl": "https://accounts.google.com/o/oauth2/v2/auth?access_type=offline&scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.upload&response_type=code&client_id=xxx&redirect_uri=xxx&prompt=consent"
 // string — Full OAuth2 URL to redirect the user to
}
```
---
### 13.2 Handle YouTube OAuth Callback
```
GET /youtube/callback
```
**Auth Required**: ❌ No (Called by Google redirect)
**Roles**: None
> Exchanges the authorization code (received from Google after user consent) for access/refresh tokens.
#### Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `code` | `string` | ✅ | Authorization code from Google OAuth redirect |
#### Response `200 OK`
```json
{
 "message": "Authentication successful", // string
 "refreshToken": "ya29.a0AfB_byC..." // string — Refresh token for future API calls
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid or expired authorization code |
---
### 13.3 Upload Video to YouTube (Standalone)
```
POST /youtube/upload
```
**Auth Required**: ✅ Requires YouTube OAuth configured (refresh token in environment)
**Roles**: Any user with YouTube credentials
**Content-Type**: `multipart/form-data`
> **Note**: For uploading course lecture videos, prefer the dedicated endpoint `POST /api/courses/:courseId/materials/video` (section 11.5) which also creates the material record.
#### Form Data Fields
| Field | Type | Required | Constraints | Description |
|---|---|---|---|---|
| `video` | `binary (file)` | ✅ | MP4, AVI, MOV, WMV, FLV, WebM | Video file |
| `title` | `string` | ✅ | — | Video title |
| `description` | `string` | ✅ | — | Video description |
| `tags` | `string` | ❌ | Comma-separated string | Tags (e.g. `"education,course,lecture"`) |
> **Note**: `tags` here is a **comma-separated string**, not an array (unlike the Course Materials video endpoint).
#### Response `201 Created`
```json
{
 "success": true, // boolean
 "videoId": "dQw4w9WgXcQ", // string — YouTube video ID
 "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", // string — Full watch URL
 "data": { // object — Full YouTube API response data
 "kind": "youtube#video",
 "etag": "...",
 "id": "dQw4w9WgXcQ",
 "snippet": {
 "title": "My Course Lecture",
 "description": "Lecture about...",
 "tags": ["education", "course", "lecture"],
 "categoryId": "22"
 },
 "status": {
 "privacyStatus": "unlisted"
 }
 }
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | No video file or invalid format |
| `401` | YouTube authentication required (no valid refresh token) |
| `413` | Video file too large |
---
### 13.4 Search YouTube Videos
```
GET /youtube/search
```
**Auth Required**: ❌ No (Uses service account OAuth2)
**Roles**: None
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `query` | `string` | ✅ | — | Search terms |
| `maxResults` | `integer` | ❌ | `10` | Max number of results (capped at 50) |
#### Response `200 OK`
```json
{
 "success": true, // boolean
 "items": [ // array — Search results
 {
 "videoId": "dQw4w9WgXcQ", // string — YouTube video ID
 "title": "Example Video Title", // string — Video title
 "description": "Video description...", // string — Truncated description
 "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", // string — HQ thumbnail URL
 "channelTitle": "Channel Name", // string — Channel name
 "publishedAt": "2023-01-15T10:30:00Z", // string — ISO 8601 publish date
 "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", // string — Watch URL
 "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ" // string — Embed URL
 }
 ],
 "totalResults": 1000000, // number — Total matching results
 "resultsPerPage": 10 // number — Results returned
}
```
#### Error Responses
| Status | Description |
|---|---|
| `400` | Invalid query parameters (missing `query`) |
---
### 13.5 Get Video Details by ID
```
GET /youtube/videos/:videoId
```
**Auth Required**: ❌ No (Uses service account OAuth2)
**Roles**: None
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `videoId` | `string` | ✅ | YouTube video ID (e.g. `dQw4w9WgXcQ`) |
#### Response `200 OK` (Found)
```json
{
 "success": true, // boolean
 "video": { // object — Complete video info
 "videoId": "dQw4w9WgXcQ", // string — YouTube ID
 "title": "Example Video", // string — Title
 "description": "Full video description...", // string — Full description
 "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", // string — Thumbnail
 "channelId": "UC1234567890", // string — Channel ID
 "channelTitle": "Channel Name", // string — Channel name
 "publishedAt": "2023-01-15T10:30:00Z", // string — Publish date
 "duration": "PT4M33S", // string — ISO 8601 duration
 "viewCount": "1000000", // string — View count
 "likeCount": "50000", // string — Like count
 "commentCount": "2000", // string — Comment count
 "privacyStatus": "public", // string — "public" | "private" | "unlisted"
 "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", // string — Watch URL
 "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ" // string — Embed URL
 }
}
```
#### Response `200 OK` (Not Found)
```json
{
 "success": false, // boolean
 "message": "Video not found" // string
}
```
> **Note**: Returns `200` with `success: false` when video doesn't exist — not a `404`.
---
### 13.6 Get Channel Videos
```
GET /youtube/channel/:channelId/videos
```
**Auth Required**: ❌ No (Uses service account OAuth2)
**Roles**: None
#### Path Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
| `channelId` | `string` | ✅ | YouTube channel ID (e.g. `UC1234567890`) |
#### Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| `maxResults` | `integer` | ❌ | `10` | Max number of results (capped at 50) |
#### Response `200 OK`
```json
{
 "success": true, // boolean
 "items": [ // array — Channel videos (newest first)
 {
 "videoId": "dQw4w9WgXcQ", // string — Video ID
 "title": "Latest Video", // string — Title
 "description": "Video description...", // string
 "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg", // string
 "publishedAt": "2023-01-15T10:30:00Z", // string — ISO 8601
 "videoUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", // string
 "embedUrl": "https://www.youtube.com/embed/dQw4w9WgXcQ" // string
 }
 ],
 "totalResults": 150, // number — Total channel videos
 "resultsPerPage": 10 // number — Results returned
}
```
#### Error Responses
| Status | Description |
|---|---|
| `404` | Channel not found |
---
## 14. Course Materials Role-Based Access Matrix
| Endpoint | Student | Instructor (assigned) | TA (assigned) | Admin / IT Admin |
|---|---|---|---|---|
| `GET .../materials` | ✅ (published only) | ✅ (all) | ✅ (all) | ✅ (all) |
| `GET .../materials/:id` | ✅ (published only) | ✅ | ✅ | ✅ |
| `POST .../materials` | ❌ | ✅ | ✅ | ✅ |
| `POST .../materials/bulk` | ❌ | ✅ | ✅ | ✅ |
| `POST .../materials/video` | ❌ | ✅ | ✅ | ✅ |
| `POST .../materials/document` | ❌ | ✅ | ✅ | ✅ |
| `PUT .../materials/:id` | ❌ | ✅ (own only) | ✅ (own only) | ✅ (any) |
| `DELETE .../materials/:id` | ❌ | ✅ (own only) | ✅ (own only) | ✅ (any) |
| `PATCH .../materials/:id/visibility` | ❌ | ✅ (own only) | ✅ (own only) | ✅ (any) |
| `GET .../materials/:id/download` | ✅ (published only) | ✅ | ✅ | ✅ |
| `POST .../materials/:id/view` | ✅ | ✅ | ✅ | ✅ |
| `GET .../materials/:id/embed` | ✅ | ✅ | ✅ | ✅ |
| `GET .../structure` | ✅ | ✅ | ✅ | ✅ |
| `GET .../structure/:id` | ✅ | ✅ | ✅ | ✅ |
| `POST .../structure` | ❌ | ✅ | ❌ | ✅ |
| `PUT .../structure/:id` | ❌ | ✅ | ❌ | ✅ |
| `DELETE .../structure/:id` | ❌ | ✅ | ❌ | ✅ |
| `PATCH .../structure/reorder` | ❌ | ✅ | ❌ | ✅ |
---
## 15. Video Lecture Viewing — End-to-End Flow
### 15.1 Instructor Uploads a Video Lecture
```mermaid
sequenceDiagram
 participant I as Instructor
 participant API as Backend API
 participant YT as YouTube API
 participant DB as Database
 I->>API: POST /api/courses/1/materials/video (multipart: video + metadata)
 API->>API: Validate user is assigned to course
 API->>YT: Upload video buffer (unlisted)
 YT-->>API: Return { videoId, videoUrl }
 API->>DB: INSERT INTO course_materials (materialType='video', youtubeVideoId, externalUrl=embed URL)
 DB-->>API: Return saved material entity
 API-->>I: 201 { materialId, youtubeVideoId, embedUrl, youtubeUrl }
```
### 15.2 Student Views a Video Lecture
```mermaid
sequenceDiagram
 participant S as Student
 participant API as Backend API
 participant DB as Database
 S->>API: GET /api/courses/1/materials?materialType=video
 API->>DB: SELECT WHERE course_id=1 AND material_type='video' AND is_published=1
 DB-->>API: Return published video materials
 API-->>S: 200 { data: [...], meta: { total, page, limit, totalPages } }
 Note over S: Student selects a video
 S->>API: POST /api/courses/1/materials/5/view
 API->>DB: UPDATE viewCount = viewCount + 1
 API-->>S: 200 { message, materialId, viewCount }
 S->>API: GET /api/courses/1/materials/5/embed
 API-->>S: 200 { videoId, embedUrl, iframeHtml }
 Note over S: Flutter renders YouTube video using embedUrl in WebView/iframe
```
### 15.3 Flutter Integration Example (Video Player)
```dart
// Fetch video material
final response = await dio.get(
 '$baseUrl/api/courses/$courseId/materials/$materialId/embed',
 options: Options(headers: {'Authorization': 'Bearer $token'}),
);
final embedUrl = response.data['embedUrl'] as String;
final videoId = response.data['videoId'] as String;
// Option 1: Use WebView for embedded YouTube
WebViewWidget(controller: WebViewController()
 ..loadRequest(Uri.parse(embedUrl)));
// Option 2: Use youtube_player_flutter package
YoutubePlayer(
 controller: YoutubePlayerController(
 initialVideoId: videoId,
 flags: YoutubePlayerFlags(autoPlay: false),
 ),
);
```
---
## 16. Course Details Handling — What Each Role Sees
### 16.1 Course Visibility & Access Per Role
#### **Student View**
- **Course Catalog**: Can browse all courses (public endpoints, no auth required)
- **Course Details** (`GET /api/courses/:id`):
 - Full course information (name, code, description, credits, level)
 - Prerequisites list
 - Available sections count
 - **Cannot see**: Other students' information, unpublished materials
- **Course Materials**:
 - Only **published** materials (`isPublished = true`)
 - Can view videos, download documents, track views
 - **Cannot see**: Draft materials, other students' submissions
- **Assignments**:
 - Only **published** assignments
 - Can submit if enrolled in the course section
 - Can view own submissions and grades
 - **Cannot see**: Other students' submissions
- **Labs**:
 - Only **published** labs
 - Can submit if enrolled (currently **no enrollment check** for labs — missing validation)
 - Can view own submissions and grades
 - Can view lab instructions
- **Sections & Schedules**: Can view all sections and schedules (public)
#### **Instructor View**
- **Teaching Courses** (`GET /api/enrollments/teaching`):
 - All sections where instructor is assigned
 - Course details, section info, semester dates
- **Course Details**:
 - Same as student view PLUS:
 - Can create/update/delete courses (if authorized)
 - Can manage sections and schedules
- **Course Materials**:
 - **All materials** (including drafts) for courses they teach
 - Can upload videos to YouTube, documents to Google Drive
 - Can organize materials by weeks using course structure
 - Can update/delete **own** materials only (admins can manage any)
- **Assignments**:
 - Can create/update/publish/close assignments
 - Can view **all submissions** for assignments in their courses
 - Can grade submissions (creates central grade record)
 - Can upload instruction files to Google Drive
- **Labs**:
 - Can create/update/publish/close labs
 - Can add instructions with file attachments
 - Can view **all submissions** and grade them
 - Can mark student attendance
 - Can upload TA materials (answer keys, rubrics)
 - **Can delete** labs
#### **Teaching Assistant (TA) View**
- **Teaching Courses**: Same as instructor (sections where assigned as TA)
- **Course Materials**:
 - **All materials** (including drafts) for courses they're assigned to
 - Can upload/create materials
 - Can update/delete **own** materials only
 - **Cannot** create/update course structure (weeks, lectures organization)
- **Assignments**:
 - Can create/update/delete assignments (same as instructor)
 - Can view all submissions and grade them
 - Can upload instruction files
- **Labs**:
 - Can create/update labs
 - Can add instructions and upload files
 - Can view all submissions and grade them
 - Can mark attendance
 - Can upload TA materials
 - **Cannot delete** labs (only instructors/admins)
- **Sections & Students**:
 - Can view enrolled students in their sections
 - Can view instructor/TA assignments
#### **Admin / IT Admin View**
- **Full Access** to all courses, sections, schedules, materials, assignments, labs
- Can manage any material (not just own)
- Can manage course structure
- Can assign instructors/TAs to sections
- Can manage student enrollments
- Can delete any resource
- IT Admin additionally has system-level access (backup, monitoring, security)
#### **Department Head View**
- **Currently NO specific access** to courses/assignments/labs features
- Only has access to:
 - Schedule templates (`/api/schedule-templates`)
 - Campus events (`/api/campus-events`)
- **Enhancement Needed**: Would need additional endpoints to view department courses overview, instructor assignments, etc.
### 16.2 Course Details Response Fields
When calling `GET /api/courses/:id`, the response includes:
```json
{
 "id": 1,
 "departmentId": 3,
 "name": "Introduction to CS",
 "code": "CS101",
 "description": "Fundamentals of programming...",
 "credits": 3,
 "level": "FRESHMAN",
 "syllabusUrl": "https://example.com/syllabus.pdf",
 "instructorId": 5, // ⭐ Primary instructor ID (may be null)
 "taIds": [1, 2], // ⭐ Array of TA user IDs (may be null)
 "status": "ACTIVE",
 "createdAt": "2025-01-15T10:00:00Z",
 "updatedAt": "2025-01-15T10:00:00Z",
 "department": {
 "id": 3,
 "name": "Computer Science",
 "code": "CS"
 },
 "prerequisites": [], // Array of prerequisite objects
 "sections": [], // Array of section objects
 "prerequisitesCount": 0, // ⭐ Convenience field
 "sectionsCount": 2 // ⭐ Convenience field
}
```
> **Note**: `instructorId` and `taIds` are stored in the `courses` table but actual section-level instructor/TA assignments are managed separately in `course_instructors` and `course_tas` tables via the enrollments module.
---
## 17. Business Logic Details
### 17.1 Assignment Submission — Enrollment Check
**Critical**: Assignment submission (`POST /api/assignments/:id/submit` and `POST /api/assignments/:id/submissions/upload`) **requires** the student to be enrolled in the assignment's course.
```typescript
// Enrollment validation in assignments.service.ts
const enrollment = await this.enrollmentRepo
 .createQueryBuilder('enrollment')
 .innerJoin('course_sections', 'section', 'section.section_id = enrollment.section_id')
 .where('enrollment.user_id = :userId', { userId })
 .andWhere('section.course_id = :courseId', { courseId: assignment.courseId })
 .andWhere('enrollment.enrollment_status = :status', { status: 'enrolled' })
 .getOne();
if (!enrollment) {
 throw new BadRequestException('Student is not enrolled in this course');
}
```
**Business Rules**:
1. Assignment must be in `published` status
2. If `availableFrom` is set, current time must be after it
3. If past `dueDate`:
 - If `lateSubmissionAllowed = false`: Throws `SubmissionDeadlinePassedException`
 - If `lateSubmissionAllowed = true`: Sets `isLate = 1`
4. **Student must be enrolled** in the course's section with status `enrolled`
5. **UPSERT Logic**:
- If latest submission is `graded`: Creates new attempt (increment `attemptNumber`)
 - If latest submission is not graded: Updates existing submission
### 17.2 Lab Submission — Missing Enrollment Check
**Important**: Lab submission (`POST /api/labs/:id/submit` and `POST /api/labs/:id/submissions/upload`) currently **does NOT check** if the student is enrolled in the course.
```typescript
// labs.service.ts — submit() method
// ⚠️ NO enrollment validation found
async submit(labId: number, userId: number, dto: SubmitLabDto): Promise<LabSubmission> {
 const lab = await this.findById(labId);
let isLate = false;
 if (lab.dueDate && new Date() > new Date(lab.dueDate)) {
 isLate = true;
 }
// UPSERT logic...
}
```
**Recommendation**: Add enrollment check similar to assignments for consistency.
### 17.3 Assignment vs Lab Submission Differences
| Feature | Assignments | Labs |
|---|---|---|
| **Late Detection** | `isLate: number` (0 or 1) | `isLate: boolean` (true/false) |
| **Attempt Tracking** | `attemptNumber` auto-incremented | No attempt tracking |
| **UPSERT Behavior** | Updates if not graded, new attempt if graded | Updates existing or creates new |
| **Enrollment Check** | ✅ Required | ❌ Missing (should be added) |
| **Get My Submission** | Returns single latest submission | Returns **array** of all submissions |
| **Submission Types** | `file`, `text`, `link`, `multiple` | `text`, `file` only |
| **Grade Integration** | Creates central grade record | Creates central grade record (only if status=`graded`) |
### 17.4 Grade Integration
Both assignments and labs automatically create records in the central `grades` table when graded:
**Assignment Grading** (`PATCH /api/assignments/:id/submissions/:subId/grade`):
```typescript
await this.gradesService.createGrade({
 userId: submission.userId,
 courseId: assignment.courseId,
 gradeType: GradeType.ASSIGNMENT,
 assignmentId: assignmentId,
 score: dto.score,
 maxScore: Number(assignment.maxScore),
 feedback: dto.feedback,
 isPublished: true, // Immediately visible
}, graderId);
```
**Lab Grading** (`PATCH /api/labs/:id/submissions/:subId/grade`):
```typescript
// Only creates grade if status is 'graded' and score provided
if (dto.score !== undefined && dto.status === 'graded') {
 await this.gradesService.createGrade({
 userId: submission.userId,
 courseId: lab.courseId,
 gradeType: GradeType.LAB,
 labId: labId,
 score: dto.score,
 maxScore: Number(lab.maxScore),
 feedback: dto.feedback,
 isPublished: true,
 }, graderId);
}
```
### 17.5 Google Drive File Organization
**Assignment Instructions**:
- Folder: `EduVerse/Courses/{CourseCode}/Assignments/Assignment_{ID}/Instructions/`
- File naming: `{Title}_v1.{ext}`
**Assignment Submissions**:
- Folder: `EduVerse/Courses/{CourseCode}/Assignments/Assignment_{ID}/Submissions/User_{UserID}/`
- File naming: `Assignment_{ID}_Submission_{YYYYMMDD}.{ext}`
**Lab Instructions**:
- Folder: `EduVerse/Courses/{CourseCode}/Labs/Lab_{LabNumber}/Instructions/`
- File naming: `{Title}_v1.{ext}`
**Lab TA Materials**:
- Folder: `EduVerse/Courses/{CourseCode}/Labs/Lab_{LabNumber}/TA_Materials/`
- File naming: `{Type}_{Title}.{ext}` (e.g., `solution_Lab_1_Answer_Key.pdf`)
**Lab Submissions**:
- Folder: `EduVerse/Courses/{CourseCode}/Labs/Lab_{LabNumber}/Submissions/User_{UserID}/`
- File naming: `Lab{LabNumber}_Submission_{YYYYMMDD}.{ext}`
### 17.6 Course Section Status Auto-Calculation
Section status is automatically calculated based on enrollment:
```typescript
private calculateSectionStatus(maxCapacity: number, currentEnrollment: number): SectionStatus {
 if (currentEnrollment >= maxCapacity) {
 return SectionStatus.FULL;
 }
 return SectionStatus.OPEN;
}
```
- `OPEN`: Enrollment < Capacity
- `FULL`: Enrollment >= Capacity
- `CLOSED`: Manually set by instructor/admin
- `CANCELLED`: Manually set by instructor/admin
---
## 18. End-to-End Flow Diagrams
### 18.1 Student Course Enrollment Flow
```mermaid
sequenceDiagram
 participant S as Student
 participant API as Backend API
 participant DB as Database
 S->>API: GET /api/enrollments/available
 API->>DB: Query active courses with sections
 DB-->>API: Return courses
 API->>API: Check prerequisites, capacity, conflicts
 API-->>S: 200 { courses with canEnroll flag }
Note over S: Student selects a section
S->>API: POST /api/enrollments/register { sectionId }
 API->>DB: Check prerequisites (grade B- or higher)
 API->>DB: Check schedule conflicts
 API->>DB: Check existing enrollment
 API->>DB: INSERT course_enrollments
 API->>DB: UPDATE sections SET currentEnrollment + 1
 API-->>S: 201 { enrollment details }
```
### 18.2 Assignment Submission Flow (with Enrollment Check)
```mermaid
sequenceDiagram
 participant S as Student
 participant API as Backend API
 participant DB as Database
 participant GD as Google Drive
 S->>API: GET /api/assignments/:id
 API->>DB: Get assignment with course info
 API-->>S: 200 { assignment details }
Note over S: Student prepares submission
S->>API: POST /api/assignments/:id/submissions/upload (multipart)
 API->>DB: Check assignment status = published
 API->>DB: Check availableFrom <= now
 API->>DB: Check dueDate (late detection)
 API->>DB: CHECK enrollment in course section ⭐
 alt Not enrolled
 API-->>S: 400 "Student is not enrolled in this course"
 else Enrolled
 API->>GD: Upload file to student folder
 GD-->>API: Return driveFileId, URLs
 API->>DB: UPSERT submission (check if graded)
 API-->>S: 201 { submission + driveFile }
 end
```
### 18.3 Lab Submission Flow (without Enrollment Check)
```mermaid
sequenceDiagram
 participant S as Student
 participant API as Backend API
 participant DB as Database
 participant GD as Google Drive
 S->>API: GET /api/labs/:id
 API->>DB: Get lab with instructions
 API-->>S: 200 { lab + instructions }
Note over S: Student prepares submission
S->>API: POST /api/labs/:id/submissions/upload (multipart)
 API->>DB: Check lab exists
 API->>DB: Check dueDate (late detection)
 API->>DB: ⚠️ NO enrollment check
 API->>GD: Upload file to student folder
 GD-->>API: Return driveFileId, URLs
 API->>DB: UPSERT submission
 API-->>S: 201 { submission + driveFile }
```
### 18.4 Grading Flow (Central Gradebook Integration)
```mermaid
sequenceDiagram
 participant I as Instructor/TA
 participant API as Backend API
 participant DB as Database
 participant GB as Grades Module
 I->>API: PATCH /api/assignments/:id/submissions/:subId/grade
 API->>DB: Get submission + assignment
 API->>DB: UPDATE submission (status=graded, score, feedback)
 API->>GB: createGrade({ assignment, score, maxScore })
 GB->>DB: INSERT grades (gradeType='assignment', isPublished=true)
 GB-->>API: Return gradeId
 API-->>I: 200 { submissionId, score, maxScore, gradeId }
```
---
## 19. UI Shape for 5 Roles
This section describes the **expected UI structure** for each role based on the backend API capabilities.
### 19.1 Student UI
#### **Dashboard / Home**
- **My Courses**: Grid/list of enrolled courses with:
 - Course name, code, instructor
 - Current grade (if available)
 - Quick links to materials, assignments, labs
- **Upcoming Deadlines**: Assignments and labs due soon
- **Recent Grades**: Latest graded submissions
#### **Course Catalog** (Public)
- Browse all courses by department, level, search
- View course details:
 - Description, credits, prerequisites
 - Available sections with schedules
 - Enroll button (if `canEnroll = true`)
#### **Course Details Page** (Per Course)
- **Tabs**:
 1. **Overview**: Description, syllabus, instructor/TA info
 2. **Materials**: Published videos, documents (organized by weeks)
 - Video player (YouTube embed)
 - Document viewer/download
 - View tracking (analytics for instructor)
 3. **Assignments**: Published assignments list
 - Title, due date, status
 - Submit button → Modal with:
 - Text editor
 - File upload
 - Link input
 - Late warning if past due
 - View submission history with grades/feedback
 4. **Labs**: Published labs list
 - Title, due date, lab number
 - View instructions (with file attachments)
 - Submit button → Modal with:
 - Text/code editor
 - File upload
 - View submission history with grades/feedback
 5. **Grades**: All graded work with scores, feedback, overall grade
 6. **Schedule**: Section schedule (days, times, rooms)
#### **Enrollment Management**
- **My Enrollments**: List of current/past courses
- **Available Courses**: Browse and register (with prerequisites check)
- **Drop Course**: Button with deadline warning
---
### 19.2 Instructor UI
#### **Dashboard / Home**
- **Teaching Courses**: Grid of assigned sections with:
 - Course name, section number
 - Enrollment count
 - Quick stats: pending submissions, upcoming deadlines
- **Recent Activity**: New submissions, recent grading
#### **Course Management** (Per Assigned Section)
- **Tabs**:
 1. **Overview**:
 - Course details (edit if assigned)
 - Section info (capacity, location)
 - Instructor/TA assignments (view only, admin manages)
 - Enrolled students list (with contact info)
2. **Materials**:
 - **All materials** (including drafts)
 - Upload buttons:
 - 📹 **Upload Video** → YouTube upload modal (title, description, tags, week)
 - 📄 **Upload Document** → Google Drive upload (title, type, week)
 - Organize by weeks (course structure):
 - Create/edit weeks, lectures, sections, labs
 - Drag-and-drop reorder
 - Toggle visibility (publish/draft)
 - View analytics (view count, download count)
3. **Assignments**:
 - List all assignments (draft/published/closed/archived)
 - **Create Assignment** modal:
 - Title, description, instructions
 - Submission type (file/text/link/multiple)
 - Due date, available from date
 - Late submission settings
 - Max score, weight
 - Allowed file types, max size
 - **View Submissions**:
 - Table of all students with:
 - Name, submission time, late flag
 - Status (submitted/graded/returned)
 - Attempt number
 - Grade input (score, feedback)
 - Bulk actions: download all, grade selected
 - **Grade Submission**:
 - Side-by-side view:
 - Left: Student submission (file viewer, text, link)
 - Right: Grade input (score, feedback, status)
4. **Labs**:
 - List all labs (draft/published/closed/archived)
 - **Create Lab** modal:
 - Title, description, lab number
 - Due date, available from
 - Max score, weight
 - **Manage Instructions**:
 - Add steps (markdown text, file attachments)
 - Reorder instructions
 - Upload instruction files to Drive
 - **View Submissions**: Same as assignments
 - **Grade Submissions**: Same as assignments
 - **Attendance**:
 - Student list with attendance status
 - Mark present/absent/excused/late
 - Export attendance
5. **Grades**:
 - Gradebook view with all graded work
 - Assignment grades, lab grades
 - Calculate overall grades
 - Export grades
6. **Schedule**:
 - Section schedules (days, times, rooms)
 - Create/edit schedules with conflict detection
7. **Analytics** (if available):
 - Student engagement (material views, downloads)
 - Grade distribution
 - Submission patterns
---
### 19.3 Teaching Assistant (TA) UI
**Similar to Instructor UI with these differences**:
#### **Restrictions**:
- ❌ **Cannot** delete labs
- ❌ **Cannot** manage course structure (weeks, lectures organization)
- ❌ **Cannot** assign/remove instructors or TAs
- ✅ **Can** create/edit/delete assignments
- ✅ **Can** create/edit labs (but not delete)
- ✅ **Can** grade all submissions
- ✅ **Can** upload instructions and TA materials
- ✅ **Can** mark lab attendance
- ✅ **Can** view all materials (including drafts)
#### **Additional TA-Specific Features**:
- **TA Materials Tab** (in Labs):
 - Upload answer keys, grading rubrics, solutions
 - Visible only to instructors and TAs (not students)
- **Responsibilities View**:
 - Shows assigned duties (e.g., "Grading labs, office hours Mon/Wed")
---
### 19.4 Admin UI
#### **Full System Access**
- All instructor/TA capabilities **without restrictions**
- Can manage **any** material (not just own)
- Can manage course structure
- Can delete any resource
#### **Admin-Specific Features**:
1. **Course Catalog Management**:
 - Create/edit/delete courses
 - Manage prerequisites (with circular dependency detection)
 - Assign departments, instructors, TAs at course level
2. **Section Management**:
 - Create/edit/delete sections
 - Set capacity, location, status
 - Override enrollment counts
3. **Instructor/TA Assignment**:
 - Assign instructors to sections (primary, co_instructor, guest)
 - Assign TAs to sections
 - View all assignments across sections
4. **Enrollment Management**:
 - View all student enrollments
 - Manually enroll/drop students
 - Override drop deadlines
 - Approve retake requests
5. **System Administration**:
 - Manage departments, semesters, programs
 - User management (create, assign roles)
 - System settings, integrations
---
### 19.5 IT Admin UI
**All Admin capabilities PLUS**:
1. **System Monitoring**:
 - Server health, performance metrics
 - Error tracking, alerts
 - SSL certificate status
2. **Database Management**:
 - Backup/restore
 - Database migrations
 - Query performance
3. **Security**:
 - Audit logs
 - IP blocking/unblocking
 - Security settings
4. **Integrations**:
 - Google Drive configuration
 - YouTube API setup
 - Email service configuration
---
### 19.6 Department Head UI
**Current State**: **Minimal access** to courses/assignments/labs
**Currently Available**:
- Schedule templates (create/manage templates)
- Campus events (create/manage events)
**Recommended Enhancements** (not yet implemented):
- Department courses overview
- Instructor assignments per course
- Enrollment statistics
- Department-level analytics
---
## 20. Missing Endpoints & Future Enhancements
### 20.1 Currently Missing Endpoints
1. **Lab Submission Enrollment Check**: Labs should validate student enrollment like assignments do
2. **Department Head Course Access**: Endpoints for department heads to view/manage department courses
3. **Waitlist Management**: Full waitlist table and enrollment logic
4. **Course Copy/Duplicate**: Clone a course with all materials, assignments, labs
5. **Bulk Enrollment**: Admin enroll multiple students at once
6. **Grade Export**: Export grades to CSV/Excel
7. **Assignment/Lab Cloning**: Duplicate for reuse in future semesters
8. **Discussion Forums**: Per-course discussion boards
9. **Announcements**: Course-wide announcements
10. **Notifications**: Push/email notifications for deadlines, grades
### 20.2 Recommended Improvements
1. **Add enrollment check to lab submission** endpoints for consistency
2. **Implement department_head role** permissions for course oversight
3. **Add soft delete** to labs (currently hard delete)
4. **Add attempt tracking** to lab submissions (like assignments)
5. **Implement waitlist** with auto-enrollment when seats open
6. **Add grade curves** and grading policies
7. **Add plagiarism detection** integration
8. **Implement real-time notifications** (WebSockets)
9. **Add course templates** for quick setup
10. **Add analytics dashboard** for instructors (engagement, grade distribution)
---
> **Last Updated**: April 2026
> **Backend Framework**: NestJS (TypeScript)
> **Database**: MySQL with TypeORM
> **File Storage**: Google Drive API
> **Video Storage**: YouTube API (unlisted uploads)
> **Authentication**: JWT with role-based access control