Teacher Substitution Management System Documentation

AI Recreation Context

This documentation is structured to enable AI-assisted recreation of the complete application. Key implementation details are organized in a logical flow:

1. System Setup: Dependencies and initial configuration
2. Core Components: Server, client, and mobile implementations
3. Data Structures: Schemas and file formats
4. Integration Points: API endpoints and data flow
5. Business Logic: Substitution algorithms and processing

Teacher Substitution Management System - Technical Documentation

System Overview

A comprehensive teacher substitution management system with web and mobile interfaces that handles teacher absences, substitute assignments, and notifications through an automated process.

Core Data Flow

1. CSV File Processing

   • System reads two primary CSV files:
     • timetable_file.csv: Contains regular class schedules
     • Substitude_file.csv: Contains substitute teacher information
   • Files are processed using CSV parser with error handling
   • Data is normalized and stored in JSON format

2. Teacher Data Processing

interface Teacher {
  id: number;
  name: string;
  phoneNumber: string | null;
  isSubstitute: boolean;
  variations?: string[]; // Different name spellings
}

• Name normalization removes titles (Sir, Miss, etc.)
• Handles multiple name variations using Levenshtein distance
• Deduplicates teacher entries
• Stores in total_teacher.json

3. Schedule Management

interface Schedule {
  id: number;
  day: string;
  period: number;
  teacherId: number;
  className: string;
}

• Validates day names and period numbers
• Stores class schedules by day
• Handles period configurations
• Maintains teacher-class assignments

4. Absence Handling

interface Absence {
  id: number;
  teacherId: number;
  date: string;
  substituteId: number | null;
  reason?: string;
  status: 'pending' | 'approved' | 'completed';
}

• Records teacher absences
• Triggers substitute assignment process
• Maintains absence history

File Structure and Purpose

Data Files (data/)

• absent_teachers.json: Currently absent teachers
• assigned_teacher.json: Substitute assignments
• class_schedules.json: Class timetables
• total_teacher.json: All teacher records
• period_config.json: Period timing settings
• sms_history.json: Notification logs

Server Components (server/)

1. Main Server (index.ts)

   • Express.js setup
   • Route registration
   • Authentication setup
   • Initial data loading

2. CSV Handler (csv-handler.ts)

   • Processes timetable_file.csv
   • Processes Substitude_file.csv
   • Validates data format
   • Normalizes teacher names

3. Storage System (storage.ts)

   • In-memory data management
   • File-based persistence
   • CRUD operations for all entities

4. Substitute Manager (substitute-manager.ts)

   • Auto-assignment algorithm
   • Workload balancing
   • Conflict prevention
   • Assignment history tracking

Client Components (client/src/)

1. Dashboard

   • Displays absent teachers
   • Shows today's substitutions
   • Quick action buttons
   • Real-time updates

2. Teacher Management

   • Teacher profiles
   • Attendance tracking
   • Schedule viewing
   • Contact management

3. Substitution Interface

   • Manual assignment
   • Auto-assignment triggers
   • Assignment review
   • Schedule conflicts

Mobile App (mobile/src/)

1. Core Features

   • Offline capability
   • Push notifications
   • Quick attendance marking
   • Schedule viewing

2. Data Sync

   • Local SQLite storage
   • Periodic server sync
   • Conflict resolution
   • Cache management

Database Schema

Teacher Table

CREATE TABLE teachers (
  id INTEGER PRIMARY KEY,
  name TEXT NOT NULL,
  phone_number TEXT,
  is_substitute BOOLEAN,
  variations TEXT
);

Schedule Table

CREATE TABLE schedules (
  id INTEGER PRIMARY KEY,
  day TEXT NOT NULL,
  period INTEGER NOT NULL,
  teacher_id INTEGER,
  class_name TEXT,
  FOREIGN KEY (teacher_id) REFERENCES teachers(id)
);

Absence Table

CREATE TABLE absences (
  id INTEGER PRIMARY KEY,
  teacher_id INTEGER,
  date TEXT NOT NULL,
  substitute_id INTEGER,
  status TEXT,
  FOREIGN KEY (teacher_id) REFERENCES teachers(id),
  FOREIGN KEY (substitute_id) REFERENCES teachers(id)
);

API Endpoints

Authentication

POST /api/login
Body: { username: string, password: string }
Response: { token: string, user: User }

GET /api/user
Headers: { Authorization: string }
Response: User

Teacher Management

GET /api/teachers
Response: Teacher[]

POST /api/teachers
Body: { name: string, phoneNumber?: string, isSubstitute: boolean }
Response: Teacher

GET /api/teacher-schedule/:teacherId
Response: Schedule[]

Absence Management

POST /api/absences
Body: { teacherId: number, date: string }
Response: Absence

GET /api/absences
Response: Absence[]

POST /api/auto-assign-substitutes
Response: { assignments: Assignment[], warnings: string[] }

Data Processing Algorithms

Teacher Name Normalization

function normalizeTeacherName(name: string): string {
  return name
    .toLowerCase()
    .replace(/(sir|miss|mr|ms|mrs|sr|dr)\.?\s*/gi, '')
    .replace(/[^a-z\s-]/g, '')
    .trim()
    .split(/\s+/)
    .filter(part => part.length > 1)
    .sort()
    .join(' ');
}

Substitute Assignment Logic

1. Get absent teachers for the day
2. Find available substitutes
3. Check substitute workload
4. Consider class compatibility
5. Avoid period conflicts
6. Assign and notify

Schedule Processing

1. Read CSV timetable
2. Validate day and period
3. Map teachers to classes
4. Store in structured format
5. Handle schedule conflicts

Implementation Steps

1. Setup Project Structure

mkdir -p server/src client/src mobile/src data
npm init -y

2. Install Dependencies

{
  "dependencies": {
    "express": "^4.18.2",
    "csv-parser": "^3.0.0",
    "date-fns": "^2.30.0",
    "react": "^18.2.0",
    "react-native": "^0.72.0",
    "typescript": "^5.0.0"
  }
}

3. Initialize Database Files

touch data/total_teacher.json
touch data/absent_teachers.json
touch data/assigned_teacher.json

4. Configure TypeScript

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  }
}

5. Start Implementation

• Set up Express server
• Create React frontend
• Implement data processing
• Add authentication
• Build mobile app

Testing Instructions

1. Data Validation

npm run test:data

Validates CSV files and data structures

2. Substitute Assignment

npm run test:assign

Tests auto-assignment algorithm

3. API Testing

npm run test:api

Validates API endpoints

Deployment Guide

1. Server Setup

• Port: 5000
• Host: 0.0.0.0
• Environment: Production

2. Data Migration

• Backup CSV files
• Validate JSON storage
• Check file permissions

3. Mobile Build

• Configure environment
• Build APK/IPA
• Test offline mode

Security Considerations

1. Data Protection

• File permissions
• Data encryption
• Secure storage

2. Authentication

• JWT tokens
• Session management
• Password hashing

3. API Security

• Rate limiting
• Input validation
• Error handling

Table of Contents

1. System Overview
2. Core Data Flow
3. File Structure and Purpose
4. Database Schema
5. API Endpoints
6. Data Processing Algorithms
7. Implementation Steps
8. Testing Instructions
9. Deployment Guide
10. Security Considerations
11. Introduction
12. System Architecture
13. Features
14. Setup Instructions
15. Detailed Component Guide
16. API Documentation
17. Mobile App
18. Data Structures
19. File Organization
20. Development Guide
21. Troubleshooting

Introduction

The Teacher Substitution Management System is a comprehensive solution for educational institutions to manage teacher absences and substitute assignments efficiently. It provides real-time tracking, automated assignments, and instant notifications.

Core Purpose

• Automate substitute teacher assignments
• Reduce administrative workload
• Ensure minimal disruption to classes
• Track attendance and substitution history
• Enable real-time schedule management
• Provide mobile access for teachers

Key Benefits

• Reduced manual coordination
• Improved response time
• Better resource utilization
• Enhanced communication
• Data-driven decision making

System Architecture

Tech Stack

• Frontend: React 18 with TypeScript
• Backend: Node.js 16+ with Express
• Mobile: React Native with Expo
• Database: File-based JSON storage
• SMS Integration: Multiple provider support
• State Management: TanStack Query
• Styling: Tailwind CSS

Key Components

1. Web Application (client/)

   • React SPA
   • Real-time updates
   • Responsive design
   • Role-based access

2. Server (server/)

   • Express API
   • File-based storage
   • Authentication system
   • SMS integration

3. Mobile App (mobile/)

   • React Native
   • Offline support
   • Push notifications
   • Quick actions

4. Shared Types (shared/)

   • TypeScript interfaces
   • Validation schemas
   • Utility types

Features

1. Teacher Management

• Teacher profiles with contact info
• Availability tracking
• Schedule management
• Specialization tracking
• History maintenance
• Contact preferences

2. Absence Management

• Quick absence recording
• Multiple day handling
• Absence categories
• Documentation upload
• History tracking
• Pattern analysis

3. Substitute Assignment

• Intelligent matching algorithm
• Workload balancing
• Conflict prevention
• Preference consideration
• Real-time assignment
• Manual override options

4. Notification System

• SMS alerts
• Custom templates
• Delivery tracking
• Bulk messaging
• Read receipts
• History logging

5. Schedule Management

• Visual timetable
• Period configuration
• Conflict detection
• Schedule export
• Calendar integration
• Quick adjustments

6. Analytics & Reporting

• Absence patterns
• Substitution stats
• Teacher workload
• System usage
• SMS delivery
• Performance metrics

Setup Instructions

Prerequisites

Node.js 16+
npm or yarn
Git

Installation Steps

1. Clone the repository
2. Install dependencies:

npm install

3. Configure environment:
   • SMS provider setup
   • Server port (default: 5000)
   • Admin account creation
   • File permissions
   • Logging setup

Data Files Setup

Required CSV files:

• timetable_file.csv: Class schedules

  • Format: Day,Period,Teacher,Class
  • Example: Monday,1,John Doe,10A

• Substitude_file.csv: Substitute details

  • Format: Name,Phone,Availability
  • Example: Jane Smith,+1234567890,M/W/F

Initial Configuration

1. Admin Setup

   • Create admin account
   • Configure SMS templates
   • Set up period timings
   • Define school schedule

2. System Checks

   • Verify file permissions
   • Test SMS delivery
   • Check file paths
   • Validate schedules

Detailed Component Guide

1. Login Page (/login)

Features:

• Secure authentication
• Role-based access
• Password recovery
• Session management
• Activity logging
• Security measures

2. Dashboard (/dashboard)

Components:

• Absent teacher count
• Today's assignments
• Quick actions menu
• Notification center
• System status
• Recent activities

3. Teacher Management (/teachers)

Features:

• Profile management
• Schedule viewing
• Contact updates
• Availability setting
• History tracking
• Document upload

4. Absence Recording (/absences)

Features:

• Quick recording
• Duration setting
• Document attachment
• History viewing
• Pattern analysis
• Bulk operations

5. Substitute Assignment (/substitutes)

Features:

• Auto assignment
• Manual override
• History tracking
• Preference setting
• Conflict checking
• Workload balancing

6. Schedule Management (/schedule)

Features:

• Timetable view
• Period management
• Conflict handling
• Export options
• Quick edits
• Calendar sync

7. Settings (/settings)

Features:

• SMS configuration
• Period timing
• System preferences
• User management
• Backup options
• Log viewing

API Documentation

Authentication

POST /api/login
  Body: { username, password }
  Response: { token, user }

GET /api/user
  Headers: { Authorization }
  Response: { user }

POST /api/logout
  Headers: { Authorization }
  Response: { success }

Teacher Management

GET /api/teachers
  Response: Teacher[]

POST /api/teachers
  Body: { name, phone, isSubstitute }
  Response: Teacher

GET /api/teacher-schedule/:teacherName
  Response: Schedule[]

Absence Management

GET /api/absences
  Response: Absence[]

POST /api/absences
  Body: { teacherId, date }
  Response: Absence

GET /api/get-absent-teachers
  Response: AbsentTeacher[]

Substitute Assignment

POST /api/auto-assign-substitutes
  Response: Assignment[]

GET /api/substitute-assignments
  Response: Assignment[]

POST /api/reset-assignments
  Response: { success }

Schedule Management

GET /api/schedule/:day
  Response: Schedule[]

POST /api/schedule
  Body: { day, periods }
  Response: Schedule

GET /api/period-config
  Response: PeriodConfig[]

Mobile App

Setup

cd mobile
npm install

Key Features

1. Attendance Marking

   • Quick mark
   • Offline support
   • Batch upload
   • History view

2. Schedule Viewing

   • Daily view
   • Weekly view
   • Quick search
   • Offline access

3. Substitute Assignment

   • Accept/reject
   • View details
   • Contact info
   • Directions

4. Push Notifications

   • Assignment alerts
   • Schedule changes
   • System updates
   • Reminders

Data Structures

Teacher

interface Teacher {
  id: number;
  name: string;
  phoneNumber: string;
  isSubstitute: boolean;
  specializations?: string[];
  availability?: string[];
  preferences?: {
    maxClassesPerDay: number;
    preferredClasses: string[];
  };
}

Schedule

interface Schedule {
  id: number;
  day: string;
  period: number;
  teacherId: number;
  className: string;
  subject?: string;
  room?: string;
}

Absence

interface Absence {
  id: number;
  teacherId: number;
  date: string;
  substituteId: number | null;
  reason?: string;
  documentation?: string[];
  status: 'pending' | 'approved' | 'completed';
}

SMS Configuration

interface SMSConfig {
  provider: string;
  apiKey: string;
  senderId: string;
  templates: {
    assignment: string;
    reminder: string;
    urgent: string;
  };
  retryConfig: {
    attempts: number;
    delay: number;
  };
}

File Storage Structure

data/
├── absent_teachers.json     # Current absences
├── assigned_teacher.json    # Substitute assignments
├── class_schedules.json    # Class-wise schedules
├── day_schedules.json      # Day-wise schedules
├── period_config.json      # Period timings
├── teacher_schedules.json  # Teacher timetables
├── total_teacher.json      # All teachers
├── users.json             # User accounts
└── sms_history.json       # Message logs

Development Guide

Best Practices

1. Code Style

   • Follow TypeScript guidelines
   • Use async/await
   • Implement error handling
   • Add proper logging

2. File Organization

   • Group by feature
   • Separate concerns
   • Use clear naming
   • Maintain hierarchy

3. Error Handling

   • Graceful failures
   • User feedback
   • Error logging
   • Recovery options

4. Performance

   • Optimize queries
   • Cache results
   • Batch operations
   • Lazy loading

Security Considerations

Data Protection

• Secure file storage
• Access control
• Data encryption
• Regular backups

Authentication

• Token-based auth
• Session management
• Password policies
• Role enforcement

API Security

• Rate limiting
• Input validation
• Error masking
• CORS policy

Troubleshooting

Common Issues

1. File Access

   • Check permissions
   • Verify paths
   • Monitor storage
   • Handle locks

2. SMS Delivery

   • Verify credentials
   • Check balance
   • Monitor status
   • Handle failures

3. Assignment Failures

   • Validate data
   • Check conflicts
   • Review logs
   • Manual override

4. Mobile Sync

   • Check connectivity
   • Verify cache
   • Handle conflicts
   • Force refresh

For detailed implementation information, refer to the source code in the respective directories.