> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pixlnext.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

# Frontend Types Documentation

This document provides comprehensive documentation for all TypeScript type definitions, interfaces, and type utilities in the STO Education Platform frontend.

## Types Overview

The application uses TypeScript extensively for type safety, with centralized type definitions that ensure consistency across components, services, and utilities.

## Type Categories

### 1. Education System Types

#### EducationSystem

```typescript theme={null}
interface EducationSystem {
  id: string;
  name: string;
}
```

**Purpose**: Represents educational systems (e.g., British, American, Egyptian)

**Usage**: Used in course creation, teacher profiles, and student enrollment

**Fields**:

* `id`: Unique identifier for the education system
* `name`: Display name of the education system

***

#### EducationGrade

```typescript theme={null}
interface EducationGrade {
  id: string;
  education_system_id: string;
  name: string;
}
```

**Purpose**: Represents grade levels within education systems

**Usage**: Used for course categorization and student level matching

**Fields**:

* `id`: Unique identifier for the grade
* `education_system_id`: Foreign key to EducationSystem
* `name`: Display name of the grade (e.g., "Grade 10", "A-Level")

***

#### EducationTerm

```typescript theme={null}
interface EducationTerm {
  id: string;
  name: string;
}
```

**Purpose**: Represents academic terms or semesters

**Usage**: Used for course scheduling and academic planning

**Fields**:

* `id`: Unique identifier for the term
* `name`: Display name of the term (e.g., "Fall 2024", "Spring 2025")

***

### 2. Subject and Course Types

#### Subject

```typescript theme={null}
interface Subject {
  id: string;
  name: string;
}
```

**Purpose**: Represents academic subjects

**Usage**: Used throughout the application for course categorization

**Fields**:

* `id`: Unique identifier for the subject
* `name`: Display name of the subject (e.g., "Mathematics", "Physics")

***

#### TeacherSubject

```typescript theme={null}
interface TeacherSubject {
  id: string;
  subject_id: string;
  education_system_id: string;
  education_grade_id: string;
  subject: {
    name: string;
  };
  education_system: {
    name: string;
  };
  education_grade: {
    name: string;
  };
}
```

**Purpose**: Represents teacher's subject expertise with related data

**Usage**: Used in teacher profiles and course matching

**Fields**:

* `id`: Unique identifier for the teacher subject
* `subject_id`: Foreign key to Subject
* `education_system_id`: Foreign key to EducationSystem
* `education_grade_id`: Foreign key to EducationGrade
* `subject`: Nested subject information
* `education_system`: Nested education system information
* `education_grade`: Nested education grade information

***

#### TeacherSubjectResponse

```typescript theme={null}
interface TeacherSubjectResponse {
  id: string;
  subject_id: string;
  education_system_id: string;
  education_grade_id: string;
  subject: {
    name: string;
  }[];
  education_system: {
    name: string;
  }[];
  education_grade: {
    name: string;
  }[];
}
```

**Purpose**: Represents teacher subjects with array responses from database

**Usage**: Used when database returns multiple related records

**Fields**: Same as TeacherSubject but with arrays for related data

***

#### Course

```typescript theme={null}
interface Course {
  id: string;
  title: string;
  cost: number;
  rating?: number;
  ratings_count?: number;
  sessions_count: number;
  session_duration: number;
  teacher: {
    first_name: string;
    last_name: string;
  };
  education_system: {
    id: string;
    name: string;
  };
  education_grade: {
    id: string;
    name: string;
  };
  subject: {
    id: string;
    name: string;
  };
}
```

**Purpose**: Represents course information with related data

**Usage**: Used throughout the application for course display and management

**Fields**:

* `id`: Unique identifier for the course
* `title`: Course title
* `cost`: Course price in EGP
* `rating`: Optional average rating (0-5)
* `ratings_count`: Optional number of ratings
* `sessions_count`: Number of sessions in the course
* `session_duration`: Duration of each session in minutes
* `teacher`: Nested teacher information
* `education_system`: Nested education system information
* `education_grade`: Nested education grade information
* `subject`: Nested subject information

***

### 3. User and Profile Types

#### Profile

```typescript theme={null}
interface Profile {
  id: string;
  first_name: string;
  last_name: string;
  gender: string;
  email: string;
  mobile: string;
  country: string;
  region: string;
  city: string;
  profile_image: string | null;
  education_system?: {
    name: string;
  };
  education_grade?: {
    name: string;
  };
}
```

**Purpose**: Represents user profile information

**Usage**: Used throughout the application for user data display

**Fields**:

* `id`: Unique identifier for the profile
* `first_name`: User's first name
* `last_name`: User's last name
* `gender`: User's gender
* `email`: User's email address
* `mobile`: User's mobile number
* `country`: User's country
* `region`: User's region/state
* `city`: User's city
* `profile_image`: Optional profile image URL
* `education_system`: Optional nested education system
* `education_grade`: Optional nested education grade

***

#### SignUpFormData

```typescript theme={null}
interface SignUpFormData {
  email: string;
  password: string;
  confirmPassword: string;
  firstName: string;
  lastName: string;
  mobile: string;
  educationSystemId?: string;
  educationGradeId?: string;
  country: string;
  region: string;
  city: string;
  userType: 'student' | 'parent' | 'teacher';
  gender: 'male' | 'female' | 'other';
  nationality?: string;
}
```

**Purpose**: Represents user registration form data

**Usage**: Used in registration forms and validation

**Fields**:

* `email`: User's email address
* `password`: User's password
* `confirmPassword`: Password confirmation
* `firstName`: User's first name
* `lastName`: User's last name
* `mobile`: User's mobile number
* `educationSystemId`: Optional education system selection
* `educationGradeId`: Optional education grade selection
* `country`: User's country
* `region`: User's region/state
* `city`: User's city
* `userType`: Type of user account
* `gender`: User's gender
* `nationality`: Optional nationality

***

### 4. Session and Attendance Types

#### SessionType

```typescript theme={null}
interface SessionType {
  id: string;
  name: string;
}
```

**Purpose**: Represents types of sessions

**Usage**: Used for session categorization and scheduling

**Fields**:

* `id`: Unique identifier for the session type
* `name`: Display name of the session type (e.g., "Live Class", "Office Hours")

***

### 5. Teacher Mark Scheme Types

#### TeacherMarkScheme

```typescript theme={null}
interface TeacherMarkScheme {
  id: string;
  subject_id: string;
  exam_category: 'AL' | 'IGCSE';
  paper_year: string;
  paper_season: 'w' | 's' | 'm';
  paper_category: string;
  original_filename: string;
  file_url: string;
  file_size: number;
  teacher_explanation: string;
  teacher_notes?: string;
  is_public: boolean;
  is_approved: boolean;
  created_at: string;
  updated_at: string;
}
```

**Purpose**: Represents teacher-created mark schemes for exam papers

**Usage**: Used in the teacher mark scheme marketplace

**Fields**:

* `id`: Unique identifier for the mark scheme
* `subject_id`: Foreign key to Subject
* `exam_category`: Type of exam (AL = A-Level, IGCSE = IGCSE)
* `paper_year`: Year of the exam paper
* `paper_season`: Season of the exam ('w' = Winter, 's' = Summer, 'm' = March)
* `paper_category`: Category of the paper
* `original_filename`: Original filename of the uploaded file
* `file_url`: URL to the mark scheme file
* `file_size`: Size of the file in bytes
* `teacher_explanation`: Teacher's explanation of the mark scheme
* `teacher_notes`: Optional additional notes
* `is_public`: Whether the mark scheme is public
* `is_approved`: Whether the mark scheme is approved
* `created_at`: Creation timestamp
* `updated_at`: Last update timestamp

***

#### TeacherMarkSchemePurchase

```typescript theme={null}
interface TeacherMarkSchemePurchase {
  id: string;
  student_id: string;
  teacher_mark_scheme_id: string;
  order_id: string;
  purchase_date: string;
  amount_paid: number;
  currency: string;
  payment_status: 'pending' | 'completed' | 'failed' | 'refunded';
  access_expires_at?: string;
  created_at: string;
  updated_at: string;
}
```

**Purpose**: Represents student purchases of teacher mark schemes

**Usage**: Used for purchase tracking and access control

**Fields**:

* `id`: Unique identifier for the purchase
* `student_id`: Foreign key to student profile
* `teacher_mark_scheme_id`: Foreign key to TeacherMarkScheme
* `order_id`: Foreign key to order record
* `purchase_date`: Date of purchase
* `amount_paid`: Amount paid for the mark scheme
* `currency`: Currency of payment (default: EGP)
* `payment_status`: Status of the payment
* `access_expires_at`: Optional access expiration date
* `created_at`: Creation timestamp
* `updated_at`: Last update timestamp

***

#### TeacherMarkSchemeWithPurchase

```typescript theme={null}
interface TeacherMarkSchemeWithPurchase extends TeacherMarkScheme {
  is_purchased?: boolean;
  purchase_details?: TeacherMarkSchemePurchase;
}
```

**Purpose**: Extends TeacherMarkScheme with purchase information

**Usage**: Used when displaying mark schemes with purchase status

**Fields**: Inherits all TeacherMarkScheme fields plus:

* `is_purchased`: Whether the current user has purchased this scheme
* `purchase_details`: Details of the purchase if applicable

***

#### TeacherMarkSchemePaymentRequest

```typescript theme={null}
interface TeacherMarkSchemePaymentRequest {
  teacher_mark_scheme_id: string;
  amount: number;
  currency?: string;
  student_id: string;
}
```

**Purpose**: Represents payment request for teacher mark scheme

**Usage**: Used in payment processing flow

**Fields**:

* `teacher_mark_scheme_id`: ID of the mark scheme to purchase
* `amount`: Amount to pay
* `currency`: Optional currency (defaults to EGP)
* `student_id`: ID of the purchasing student

***

#### TeacherMarkSchemePaymentResponse

```typescript theme={null}
interface TeacherMarkSchemePaymentResponse {
  success: boolean;
  payment_url?: string;
  order_id?: string;
  error?: string;
}
```

**Purpose**: Represents response from payment request

**Usage**: Used for handling payment responses

**Fields**:

* `success`: Whether the payment request was successful
* `payment_url`: Optional URL for payment processing
* `order_id`: Optional order ID for tracking
* `error`: Optional error message

***

## Type Utilities and Helpers

### 1. Union Types

#### User Types

```typescript theme={null}
type UserType = 'student' | 'parent' | 'teacher' | 'admin' | 'trainee';
```

#### Gender Types

```typescript theme={null}
type Gender = 'male' | 'female' | 'other';
```

#### Payment Status Types

```typescript theme={null}
type PaymentStatus = 'pending' | 'completed' | 'failed' | 'refunded';
```

#### Exam Category Types

```typescript theme={null}
type ExamCategory = 'AL' | 'IGCSE';
```

#### Paper Season Types

```typescript theme={null}
type PaperSeason = 'w' | 's' | 'm';
```

### 2. Utility Types

#### Partial Profile

```typescript theme={null}
type PartialProfile = Partial<Profile>;
```

#### Required Course Fields

```typescript theme={null}
type RequiredCourseFields = Required<Pick<Course, 'title' | 'cost' | 'sessions_count'>>;
```

#### Optional Mark Scheme Fields

```typescript theme={null}
type OptionalMarkSchemeFields = Pick<TeacherMarkScheme, 'teacher_notes'>;
```

### 3. Generic Types

#### API Response

```typescript theme={null}
interface ApiResponse<T> {
  data: T;
  error?: string;
  success: boolean;
}
```

#### Paginated Response

```typescript theme={null}
interface PaginatedResponse<T> {
  data: T[];
  page: number;
  limit: number;
  total: number;
  hasMore: boolean;
}
```

#### Form State

```typescript theme={null}
interface FormState<T> {
  values: T;
  errors: Partial<Record<keyof T, string>>;
  isSubmitting: boolean;
  isValid: boolean;
}
```

***

## Type Guards

### 1. User Type Guards

```typescript theme={null}
function isStudent(user: Profile): boolean {
  return user.userType === 'student';
}

function isTeacher(user: Profile): boolean {
  return user.userType === 'teacher';
}

function isAdmin(user: Profile): boolean {
  return user.userType === 'admin';
}
```

### 2. Payment Type Guards

```typescript theme={null}
function isPaymentCompleted(purchase: TeacherMarkSchemePurchase): boolean {
  return purchase.payment_status === 'completed';
}

function isPaymentPending(purchase: TeacherMarkSchemePurchase): boolean {
  return purchase.payment_status === 'pending';
}
```

### 3. Course Type Guards

```typescript theme={null}
function hasRating(course: Course): course is Course & { rating: number; ratings_count: number } {
  return course.rating !== undefined && course.ratings_count !== undefined;
}
```

***

## Type Validation

### 1. Runtime Type Checking

```typescript theme={null}
function validateSignUpData(data: any): data is SignUpFormData {
  return (
    typeof data.email === 'string' &&
    typeof data.password === 'string' &&
    typeof data.firstName === 'string' &&
    typeof data.lastName === 'string' &&
    ['student', 'parent', 'teacher'].includes(data.userType)
  );
}
```

### 2. Type Assertions

```typescript theme={null}
function assertIsCourse(obj: any): asserts obj is Course {
  if (!obj.id || !obj.title || typeof obj.cost !== 'number') {
    throw new Error('Invalid course object');
  }
}
```

***

## Type Documentation Standards

### 1. Interface Documentation

```typescript theme={null}
/**
 * Represents a user profile in the system
 * @interface Profile
 */
interface Profile {
  /** Unique identifier for the profile */
  id: string;
  
  /** User's first name */
  first_name: string;
  
  /** User's last name */
  last_name: string;
  
  /** User's email address */
  email: string;
}
```

### 2. Generic Type Documentation

```typescript theme={null}
/**
 * Generic API response wrapper
 * @template T The type of data being returned
 */
interface ApiResponse<T> {
  /** The response data */
  data: T;
  
  /** Optional error message */
  error?: string;
  
  /** Whether the request was successful */
  success: boolean;
}
```

### 3. Union Type Documentation

```typescript theme={null}
/**
 * Supported user types in the system
 * - student: Regular student user
 * - parent: Parent of a student
 * - teacher: Teacher user
 * - admin: Administrative user
 * - trainee: Teacher trainee
 */
type UserType = 'student' | 'parent' | 'teacher' | 'admin' | 'trainee';
```

***

## Type Best Practices

### 1. Naming Conventions

* **Interfaces**: PascalCase (e.g., `UserProfile`)
* **Types**: PascalCase (e.g., `UserType`)
* **Enums**: PascalCase (e.g., `PaymentStatus`)
* **Generic Parameters**: Single uppercase letter (e.g., `T`, `K`, `V`)

### 2. Type Organization

* **Group Related Types**: Keep related types together
* **Use Extensions**: Extend interfaces when appropriate
* **Avoid Any**: Minimize use of `any` type
* **Use Union Types**: Use union types for variants

### 3. Type Safety

* **Strict Mode**: Use strict TypeScript configuration
* **Type Guards**: Implement runtime type checking
* **Validation**: Validate data at runtime
* **Error Handling**: Handle type errors gracefully

***

## Future Type Enhancements

### 1. Planned Features

* **Advanced Generics**: More sophisticated generic types
* **Template Literal Types**: String manipulation types
* **Conditional Types**: Advanced conditional type logic
* **Mapped Types**: Dynamic type generation

### 2. Type System Improvements

* **Better Error Messages**: Enhanced TypeScript error messages
* **Type Inference**: Improved automatic type inference
* **Performance**: Better TypeScript compilation performance
* **Tooling**: Enhanced TypeScript tooling support

### 3. Developer Experience

* **Auto-completion**: Better IDE auto-completion
* **Type Hints**: Enhanced type hints and suggestions
* **Documentation**: Better type documentation
* **Testing**: Type-level testing utilities