​

Frontend Types Documentation

​

Types Overview

​

Type Categories

​

1. Education System Types

​

EducationSystem

interface EducationSystem {
  id: string;
  name: string;
}

• 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;
}

• 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;
}

• 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;
}

• 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;
  };
}

• 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;
  }[];
}

​

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;
  };
}

• 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;
  };
}

• 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;
}

• 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;
}

• 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;
}

• 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;
}

• 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;
}

• 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;
}

• 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;
}

• 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