YeboLearn Services Deep Dive

Complete documentation of every backend service with methods, parameters, and functionality.

AIService

Location: backend/src/services/aiService.ts

AI-powered features using Google Gemini.

Methods

generateDailyReport(data)

Generates a daily progress report for a student.

interface DailyReportData {
  studentName: string;
  attendanceToday: 'present' | 'absent' | 'late' | 'excused';
  recentGrades: { subject: string; score: number; maxScore: number; date: string }[];
  behaviorNotes?: string;
  classParticipation?: string;
}

// Returns: string (2-3 paragraph report)

generateWeeklyReport(data)

Comprehensive weekly summary.

interface WeeklyReportData {
  studentName: string;
  weekStartDate: string;
  weekEndDate: string;
  attendanceRate: number;
  grades: { subject: string; averageScore: number; trend: 'improving' | 'stable' | 'declining' }[];
  strengths: string[];
  areasForImprovement: string[];
}

gradeEssay(data)

AI-assisted essay grading with rubric.

interface EssayGradingData {
  essayText: string;
  rubric: { criteria: string; maxPoints: number }[];
  gradingGuidelines?: string;
}

// Returns:
interface GradingResult {
  totalScore: number;
  maxScore: number;
  feedback: string;
  criteriaScores: { criteria: string; score: number; feedback: string }[];
}

generateLessonPlan(data)

Creates comprehensive lesson plans.

interface LessonPlanInput {
  subject: string;
  topic: string;
  gradeLevel: string;
  duration: number;  // minutes
  learningObjectives?: string[];
  curriculumFramework?: string;
}

// Returns:
interface LessonPlan {
  title: string;
  objectives: string[];
  materials: string[];
  introduction: string;
  mainActivity: string;
  assessment: string;
  conclusion: string;
  homework?: string;
}

generateQuiz(data)

Auto-generates quizzes with multiple question types.

interface QuizInput {
  subject: string;
  topic: string;
  gradeLevel: string;
  numberOfQuestions: number;
  questionTypes?: ('multiple-choice' | 'true-false' | 'short-answer')[];
}

tutorHelp(data)

24/7 AI homework assistance.

// Guides students step-by-step, doesn't just give answers
async tutorHelp(data: {
  question: string;
  subject: string;
  gradeLevel: string;
  context?: string;
}): Promise<string>

generateLearningPath(data)

Personalized multi-week learning plans.

interface LearningPathInput {
  studentName: string;
  subject: string;
  currentLevel: string;
  strengths: string[];
  weaknesses: string[];
  goals: string[];
}

// Returns 4-8 week path with weekly topics, activities, and resources

---

AuthService

Location: backend/src/services/auth.service.ts

Handles authentication, password management, and session security.

Methods

register(data)

interface RegisterData {
  school_id?: string;
  email: string;
  password: string;  // Validated against PasswordPolicy
  first_name: string;
  last_name: string;
  phone?: string;
  role: UserRole;
}

// Returns: { user, accessToken, refreshToken }

Security Features:

• Password policy validation (length, complexity, no personal info)
• Account lockout protection
• Token versioning

login(email, password, schoolId?)

// Security: 
// - 5 failed attempts = 30 min lockout
// - Audit logging on success/failure
// - Token version check

// Returns: { user, accessToken, refreshToken }

refreshAccessToken(refreshToken)

Rotates tokens securely:

• Verifies refresh token validity
• Checks token version matches DB
• Issues new token pair
• Deletes old refresh token

changePassword(userId, currentPassword, newPassword)

// Security:
// - Validates new password against policy
// - Prevents password reuse
// - Increments token_version (invalidates all sessions)
// - Audit logs the change

logoutAllDevices(userId)

Invalidates all sessions by incrementing token_version.

---

StudentService

Location: backend/src/services/student.service.ts

Student lifecycle management.

Methods

Method	Parameters	Description
createStudent	{ school_id, first_name, last_name, ... }	Creates student with auto-provisioned guardian link
getStudentById	id, schoolId	Fetches with class/guardian joins
updateStudent	id, schoolId, data	Updates profile
deleteStudent	id, schoolId	Soft-delete
listStudents	schoolId, filters	Paginated list with search
assignToClass	studentId, classId	Class assignment

---

TeacherService

Location: backend/src/services/teacherService.ts

Methods

Method	Description
createTeacher	Creates teacher user with subjects
getTeacherById	With classes and subjects
assignSubjects	Link teacher to subjects
getTeacherSchedule	Weekly class schedule
getTeacherClasses	All assigned classes

---

GradeService

Location: backend/src/services/gradeService.ts

Academic performance tracking.

Methods

// Create grade entry
async createGrade(data: {
  student_id: string;
  subject_id: string;
  school_id: string;
  assessment_type: 'quiz' | 'test' | 'exam' | 'assignment';
  score: number;
  max_score: number;
  teacher_id: string;
  term?: string;
}): Promise<Grade>

// Get student grades
async getStudentGrades(studentId: string, schoolId: string, filters?: {
  subjectId?: string;
  term?: string;
  dateFrom?: Date;
  dateTo?: Date;
}): Promise<Grade[]>

// Calculate GPA
async calculateGPA(studentId: string, schoolId: string, term?: string): Promise<number>

// Class grade analytics
async getClassGradeDistribution(classId: string): Promise<GradeDistribution>

---

AttendanceService

Location: backend/src/services/attendance.service.ts

Methods

// Mark attendance
async markAttendance(data: {
  student_id: string;
  class_id: string;
  date: Date;
  status: 'present' | 'absent' | 'late' | 'excused';
  marked_by: string;
  notes?: string;
}): Promise<Attendance>

// Bulk mark (teacher marking entire class)
async bulkMarkAttendance(classId: string, date: Date, records: AttendanceRecord[]): Promise<void>

// Get attendance stats
async getStudentAttendanceRate(studentId: string, dateRange: DateRange): Promise<{
  present: number;
  absent: number;
  late: number;
  excused: number;
  rate: number;  // percentage
}>

---

FeeService

Location: backend/src/services/feeService.ts

School fee management.

Methods

Method	Description
createFeeStructure	Define fee items per term
generateInvoice	Create invoice for student
recordPayment	Log payment against invoice
getStudentBalance	Outstanding amount
getPaymentHistory	Student payment records
sendPaymentReminder	Via notification service

---

NotificationService

Location: backend/src/services/notification.service.ts

Multi-channel notifications.

async sendNotification(data: {
  userId: string;
  type: 'in_app' | 'email' | 'sms' | 'whatsapp' | 'push';
  title: string;
  body: string;
  action_url?: string;
  data?: Record<string, unknown>;
}): Promise<void>

// Bulk notifications
async sendBulkNotification(userIds: string[], notification: NotificationData): Promise<void>

// Get user notifications
async getUserNotifications(userId: string, options: {
  unreadOnly?: boolean;
  limit?: number;
  offset?: number;
}): Promise<Notification[]>

---

AnalyticsService

Location: backend/src/services/analytics.service.ts

Reporting and insights.

Methods

// School-wide dashboard
async getSchoolAnalytics(schoolId: string): Promise<{
  totalStudents: number;
  totalTeachers: number;
  attendanceRate: number;
  averageGPA: number;
  feeCollectionRate: number;
}>

// Student performance trends
async getStudentPerformanceTrend(studentId: string, months: number): Promise<TrendData[]>

// Class comparison
async getClassComparison(schoolId: string, subjectId: string): Promise<ClassComparison[]>

// Subject analytics
async getSubjectAnalytics(schoolId: string, subjectId: string): Promise<SubjectAnalytics>

---

Other Services

Service	Purpose
ClassService	Class/section management
SubjectService	Subject CRUD
GuardianService	Parent/guardian management
MessageService	In-app messaging
UploadService	File uploads to R2
ReportService	Report card generation
FlashcardService	Study flashcards
AvatarTeacherService	AI avatar tutor
GamificationService	Points, badges, leaderboards
AuditLogService	Security audit trail
OnboardingService	School onboarding wizard
SchoolManagementService	Platform admin school ops
PlatformAuthService	Super admin auth