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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

type UserType = 'student' | 'parent' | 'teacher' | 'admin' | 'trainee';

Gender Types

type Gender = 'male' | 'female' | 'other';

Payment Status Types

type PaymentStatus = 'pending' | 'completed' | 'failed' | 'refunded';

Exam Category Types

type ExamCategory = 'AL' | 'IGCSE';

Paper Season Types

type PaperSeason = 'w' | 's' | 'm';

2. Utility Types

Partial Profile

type PartialProfile = Partial<Profile>;

Required Course Fields

type RequiredCourseFields = Required<Pick<Course, 'title' | 'cost' | 'sessions_count'>>;

Optional Mark Scheme Fields

type OptionalMarkSchemeFields = Pick<TeacherMarkScheme, 'teacher_notes'>;

3. Generic Types

API Response

interface ApiResponse<T> {
  data: T;
  error?: string;
  success: boolean;
}

Paginated Response

interface PaginatedResponse<T> {
  data: T[];
  page: number;
  limit: number;
  total: number;
  hasMore: boolean;
}

Form State

interface FormState<T> {
  values: T;
  errors: Partial<Record<keyof T, string>>;
  isSubmitting: boolean;
  isValid: boolean;
}

Type Guards

1. User Type Guards

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

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

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

3. Course Type Guards

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

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

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

/**
 * 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

/**
 * 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

/**
 * 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

​Frontend Types Documentation

​Types Overview

​Type Categories

​1. Education System Types

​EducationSystem

​EducationGrade

​EducationTerm

​2. Subject and Course Types

​Subject

​TeacherSubject

​TeacherSubjectResponse

​Course

​3. User and Profile Types

​Profile

​SignUpFormData

​4. Session and Attendance Types

​SessionType

​5. Teacher Mark Scheme Types

​TeacherMarkScheme

​TeacherMarkSchemePurchase

​TeacherMarkSchemeWithPurchase

​TeacherMarkSchemePaymentRequest

​TeacherMarkSchemePaymentResponse

​Type Utilities and Helpers

​1. Union Types

​User Types

​Gender Types

​Payment Status Types

​Exam Category Types

​Paper Season Types

​2. Utility Types

​Partial Profile

​Required Course Fields

​Optional Mark Scheme Fields

​3. Generic Types

​API Response

​Paginated Response

​Form State

​Type Guards

​1. User Type Guards

​2. Payment Type Guards

​3. Course Type Guards

​Type Validation

​1. Runtime Type Checking

​2. Type Assertions

​Type Documentation Standards

​1. Interface Documentation

​2. Generic Type Documentation

​3. Union Type Documentation

​Type Best Practices

​1. Naming Conventions

​2. Type Organization

​3. Type Safety

​Future Type Enhancements

​1. Planned Features

​2. Type System Improvements

​3. Developer Experience