Frontend Utilities Documentation

This document provides comprehensive documentation for all utility functions, classes, and helper modules in the STO Education Platform frontend.

Utilities Overview

The application includes various utility modules that provide common functionality, helper functions, and specialized tools used throughout the application.

Utility Categories

1. Update Detection Utility

Location: `src/utils/updateDetector.ts`

Purpose

Handles automatic detection of application updates and notifies users when new versions are available.

Features

Version Comparison: Compares current app version with server version
Multiple Detection Methods: Uses version numbers, build times, and hashes
Automatic Monitoring: Periodic checks for updates
User Notifications: Notifies users when updates are available
Cooldown System: Prevents excessive update checks
Event-driven: Listener pattern for update notifications

Classes

UpdateDetector

class UpdateDetector {
  private currentVersion: string;
  private currentBuildTime: string;
  private currentHash: string;
  private checkInterval: number;
  private isChecking: boolean;
  private listeners: Array<(updateAvailable: boolean) => void>;
  private lastUpdateCheck: number;
  private updateCheckCooldown: number;
}

Interfaces

UpdateInfo

interface UpdateInfo {
  version: string;
  buildTime: string;
  hash: string;
}

ServerVersionInfo

interface ServerVersionInfo {
  version: string;
  buildTime: string;
  hash: string;
  lastModified?: string;
}

Key Methods

Constructor

constructor(checkIntervalMinutes: number = 5)

Initializes the update detector
Sets up version information from various sources
Configures check interval (default: 5 minutes)
Logs initialization information

startMonitoring

public startMonitoring(): void

Starts automatic update monitoring
Performs immediate check for updates
Sets up periodic checking interval
Listens for page visibility changes
Listens for window focus events

checkForUpdates

private async checkForUpdates(): Promise<boolean>

Checks for application updates
Implements cooldown system to prevent excessive checks
Compares current version with server version
Returns true if update is available

getCurrentVersion

private getCurrentVersion(): string

Retrieves current application version
Tries multiple sources:
1. Vite injected globals (__APP_VERSION__)
2. Meta tags (meta[name="app-version"])
3. Environment variables (VITE_APP_VERSION)

getCurrentBuildTime

private getCurrentBuildTime(): string

Retrieves current build time
Tries multiple sources:
1. Vite injected globals (__BUILD_TIME__)
2. Meta tags (meta[name="build-time"])
3. Environment variables (VITE_BUILD_TIME)

getCurrentHash

private getCurrentHash(): string

Retrieves current build hash
Tries multiple sources:
1. Vite injected globals (__BUILD_HASH__)
2. Meta tags (meta[name="build-hash"])
3. Environment variables (VITE_BUILD_HASH)

compareVersions

private compareVersions(current: string, latest: string): number

Compares semantic version numbers
Returns -1 if update needed, 0 if equal, 1 if current is newer
Handles version parts of different lengths

compareBuildTimes

private compareBuildTimes(current: string, server: string): boolean

Compares build timestamps
Normalizes dates to ignore seconds and milliseconds
Returns true if server build is newer

getServerVersion

public async getServerVersion(): Promise<string>

Fetches server version from /version.json
Handles network errors gracefully
Returns ‘unknown’ if fetch fails

onUpdateAvailable

public onUpdateAvailable(callback: (updateAvailable: boolean) => void): void

Registers update notification listener
Allows components to subscribe to update events

removeListener

public removeListener(callback: (updateAvailable: boolean) => void): void

Removes update notification listener
Cleans up event handlers

forceCheck

public forceCheck(): void

Forces immediate update check
Bypasses cooldown system
Useful for manual update checking

Update Detection Methods

1. Version Number Comparison

Compares semantic version numbers (e.g., “1.2.3”)
Most reliable method for major updates

2. Build Time Comparison

Compares build timestamps
Useful for detecting minor updates
Normalizes timestamps for accurate comparison

3. Build Hash Comparison

Compares build hashes
Detects any code changes
Most sensitive detection method

Usage Example

import { updateDetector } from '../utils/updateDetector';

// Start monitoring for updates
updateDetector.startMonitoring();

// Listen for update notifications
updateDetector.onUpdateAvailable((hasUpdate) => {
  if (hasUpdate) {
    // Show update notification to user
    showUpdateModal();
  }
});

// Force immediate check
updateDetector.forceCheck();

Singleton Instance

export const updateDetector = new UpdateDetector(5); // Check every 5 minutes

Integration with Vite

The utility integrates with Vite’s build process through:

Global Variables: Injected via vite.config.ts
Meta Tags: Generated during build
Version File: Creates /public/version.json

Error Handling

Network Errors: Graceful handling of fetch failures
Parse Errors: Safe JSON parsing with fallbacks
Invalid Versions: Handles malformed version strings
Missing Data: Fallbacks for missing version information

Performance Considerations

Cooldown System: Prevents excessive API calls
Lazy Loading: Only checks when needed
Efficient Comparison: Optimized version comparison algorithms
Memory Management: Proper cleanup of event listeners

Custom Hooks

1. Mochi Events Hook

Location: `src/hooks/useMochiEvents.ts`

Purpose

Provides real-time event handling for the Mochi gamification system using Supabase real-time subscriptions.

Features

Real-time Subscriptions: Listens to database changes
Toast Notifications: Shows user-friendly notifications
Event Filtering: Filters relevant events for Mochi reactions
Automatic Cleanup: Unsubscribes from channels on unmount

Implementation

export function useMochiEvents() {
  useEffect(() => {
    // Assignment submission listener
    const assignmentChannel = supabase
      .channel('assignment_submissions_mochi')
      .on('postgres_changes', {
        event: 'INSERT',
        schema: 'public',
        table: 'assignment_submissions'
      }, (payload) => {
        toast.success("🍡 Mochi is proud of your submission! Keep it up!", {
          position: "bottom-right",
          autoClose: 3000,
        });
      })
      .subscribe();

    // Session attendance listener
    const attendanceChannel = supabase
      .channel('session_attendance_mochi')
      .on('postgres_changes', {
        event: 'INSERT',
        schema: 'public',
        table: 'session_attendance'
      }, (payload) => {
        if (payload.new.status === 'attended') {
          toast.success("🎉 Mochi is happy you attended class!", {
            position: "bottom-right",
            autoClose: 3000,
          });
        }
      })
      .subscribe();

    // Cleanup function
    return () => {
      assignmentChannel.unsubscribe();
      attendanceChannel.unsubscribe();
    };
  }, []);
}

Event Types

Assignment Submissions

Table: assignment_submissions
Event: INSERT
Action: Shows congratulatory message
Message: ”🍡 Mochi is proud of your submission! Keep it up!”

Session Attendance

Table: session_attendance
Event: INSERT
Condition: Only for attended sessions
Action: Shows attendance celebration
Message: ”🎉 Mochi is happy you attended class!”

Usage Example

import { useMochiEvents } from '../hooks/useMochiEvents';

function StudentDashboard() {
  useMochiEvents(); // Enables Mochi event notifications
  
  return (
    <div>
      {/* Dashboard content */}
    </div>
  );
}

Dependencies

Supabase: Real-time subscriptions
React Toastify: Toast notifications
React: useEffect hook for lifecycle management

Type Definitions

Location: `src/lib/types.ts`

Purpose

Centralized TypeScript type definitions for the entire application.

Core Types

Education System Types

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

interface EducationGrade {
  id: string;
  education_system_id: string;
  name: string;
}

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

Teacher Subject Types

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

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

User Registration Types

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

Course Types

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

Profile Types

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

Teacher Mark Scheme Types

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

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

interface TeacherMarkSchemeWithPurchase extends TeacherMarkScheme {
  is_purchased?: boolean;
  purchase_details?: TeacherMarkSchemePurchase;
}

interface TeacherMarkSchemePaymentRequest {
  teacher_mark_scheme_id: string;
  amount: number;
  currency?: string;
  student_id: string;
}

interface TeacherMarkSchemePaymentResponse {
  success: boolean;
  payment_url?: string;
  order_id?: string;
  error?: string;
}

Library Utilities

1. Authentication Utilities

Location: `src/lib/auth.ts`

Purpose

Provides authentication-related utility functions and helpers.

Features

User Session Management: Handles user session operations
Profile Retrieval: Fetches user profile information
Session Validation: Validates user sessions
Error Handling: Comprehensive error handling

Key Functions

// Get current user from session
async function getCurrentUser() {
  const { data: { session } } = await supabase.auth.getSession();
  return session?.user ?? null;
}

// Get user profile
async function getUserProfile(userId: string) {
  const { data, error } = await supabase
    .from('profiles')
    .select('*')
    .eq('id', userId)
    .single();
  
  return { data, error };
}

2. Payment Utilities

Location: `src/lib/paymob.ts`

Purpose

Handles PayMob payment gateway integration and payment processing.

Features

Payment Intent Creation: Creates payment intentions
Payment Link Generation: Generates payment URLs
Billing Data Handling: Manages billing information
Error Handling: Comprehensive payment error handling

Key Functions

// Create payment intention
async function createPaymentIntention(
  config: PaymobConfig,
  request: PaymentRequest
): Promise<string>

// Generate payment link
function generatePaymentLink(
  publicKey: string, 
  clientSecret: string
): string

3. Analytics Utilities

Location: `src/lib/posthog.ts`

Purpose

Provides PostHog analytics integration with custom hooks and utility functions.

Features

Event Tracking: Custom event tracking
User Identification: User identification and properties
Feature Flags: Feature flag support
Group Analytics: Group-based analytics

Custom Hook

export const useAnalytics = () => {
  const posthog = usePostHog();
  
  return {
    track: (event: string, properties?: Record<string, any>) => void;
    identify: (userId: string, properties?: Record<string, any>) => void;
    setUser: (properties: Record<string, any>) => void;
    reset: () => void;
    isFeatureEnabled: (flag: string): boolean;
    group: (groupType: string, groupKey: string, properties?: Record<string, any>) => void;
  };
};

4. Supabase Utilities

Location: `src/lib/supabase.ts`

Purpose

Provides Supabase client configuration and initialization.

Implementation

import { createClient } from '@supabase/supabase-js';

const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY;

export const supabase = createClient(supabaseUrl, supabaseAnonKey);

Utility Best Practices

1. Error Handling

Graceful Degradation: Handle errors without breaking functionality
User-friendly Messages: Provide clear error messages
Logging: Comprehensive error logging for debugging
Fallbacks: Provide fallback values when possible

2. Performance Optimization

Lazy Loading: Load utilities only when needed
Caching: Cache expensive operations
Debouncing: Prevent excessive function calls
Memory Management: Proper cleanup of resources

3. Type Safety

TypeScript Interfaces: Define clear interfaces
Generic Types: Use generics for reusable utilities
Type Guards: Implement type checking functions
Documentation: Document type definitions

4. Testing

Unit Tests: Test individual utility functions
Integration Tests: Test utility integrations
Mock Dependencies: Mock external dependencies
Edge Cases: Test error conditions and edge cases

Future Utility Enhancements

1. Planned Features

Caching Layer: Implement utility-level caching
Performance Monitoring: Add performance metrics
Advanced Error Handling: Enhanced error recovery
Utility Composition: Better utility composition patterns

2. Performance Improvements

Bundle Optimization: Optimize utility bundle size
Tree Shaking: Better tree shaking support
Lazy Loading: Advanced lazy loading strategies
Memory Optimization: Better memory management

3. Developer Experience

Better Documentation: Enhanced documentation
Development Tools: Better development utilities
Debugging Support: Enhanced debugging capabilities
Testing Utilities: Better testing support

Getting Started

Frontend Development

Backend Development

Configuration & Setup

Third-Party Integrations

Scripts & Automation

Public Assets & Resources

Database & Migrations

Documentation Files

​Frontend Utilities Documentation

​Utilities Overview

​Utility Categories

​1. Update Detection Utility

​Location: src/utils/updateDetector.ts

​Purpose

​Features

​Classes

UpdateDetector

​Interfaces

UpdateInfo

ServerVersionInfo

​Key Methods

Constructor

startMonitoring

checkForUpdates

getCurrentVersion

getCurrentBuildTime

getCurrentHash

compareVersions

compareBuildTimes

getServerVersion

onUpdateAvailable

removeListener

forceCheck

​Update Detection Methods

1. Version Number Comparison

2. Build Time Comparison

3. Build Hash Comparison

​Usage Example

​Singleton Instance

​Integration with Vite

​Error Handling

​Performance Considerations

​Custom Hooks

​1. Mochi Events Hook

​Location: src/hooks/useMochiEvents.ts

​Purpose

​Features

​Implementation

​Event Types

Assignment Submissions

Session Attendance

​Usage Example

​Dependencies

​Type Definitions

​Location: src/lib/types.ts

​Purpose

​Core Types

Education System Types

Teacher Subject Types

User Registration Types

Course Types

Profile Types

Teacher Mark Scheme Types

​Library Utilities

​1. Authentication Utilities

​Location: src/lib/auth.ts

​Purpose

​Features

​Key Functions

​2. Payment Utilities

​Location: src/lib/paymob.ts

​Purpose

​Features

​Key Functions

​3. Analytics Utilities

​Location: src/lib/posthog.ts

​Purpose

​Features

​Custom Hook

Frontend Utilities Documentation

Utilities Overview

Utility Categories

1. Update Detection Utility

Location: `src/utils/updateDetector.ts`

Purpose

Features

Classes

Interfaces

Key Methods

Update Detection Methods

Usage Example

Singleton Instance

Integration with Vite

Error Handling

Performance Considerations

Custom Hooks

1. Mochi Events Hook

Location: `src/hooks/useMochiEvents.ts`

Purpose

Features

Implementation

Event Types

Usage Example

Dependencies

Type Definitions

Location: `src/lib/types.ts`

Purpose

Core Types

Library Utilities

1. Authentication Utilities

Location: `src/lib/auth.ts`

Purpose

Features

Key Functions

2. Payment Utilities

Location: `src/lib/paymob.ts`

Purpose

Features

Key Functions

3. Analytics Utilities

Location: `src/lib/posthog.ts`

Purpose

Features

Custom Hook

4. Supabase Utilities

Location: `src/lib/supabase.ts`

Purpose

Implementation

Utility Best Practices

1. Error Handling

2. Performance Optimization

3. Type Safety

4. Testing

Future Utility Enhancements

1. Planned Features

2. Performance Improvements

3. Developer Experience