YeboLearn - Product Requirements Document

Version: 2.0 Last Updated: 2026-03-19 Status: Production Ready Author: YeboLearn Team

Vision & Problem Statement
Solution Overview
Product Architecture
Core Features by User Type
Data Models
API Reference
Yebo Kids PWA
Dashboard Breakdown
Authentication & Authorization
Billing & Pricing
Technical Stack
Gaps & Missing Features

1. Vision & Problem Statement

1.1 The Problem

African schools face unique challenges that existing EdTech solutions don't address:

Fragmented Systems: Schools use multiple disconnected tools for attendance, grades, fees, and communication
Limited Technology Access: Many schools lack technical infrastructure and internet reliability
Curriculum Diversity: Each African country has its own curriculum (CAPS, CBC, SGCSE, GCE, etc.)
Language Barriers: Students need support in local languages alongside English
Home Learning Gap: Parents lack tools to support their children's education at home
Early Childhood Neglect: ECD centers have no purpose-built management tools
Payment Challenges: Schools need mobile money integration (MTN MoMo, etc.) alongside traditional payments

1.2 Our Vision

YeboLearn is a comprehensive African education platform that unifies:

School Management - Complete SIS for schools of all levels (ECD → University)
Home Learning - B2C app for parents to support their children's education
Yebo Kids - Engaging PWA for early childhood learning (ages 2-8)
AI Tutoring - Avatar-based AI teachers aligned with African curricula

1.3 Target Markets

Country	Primary Curriculum	Currency	Status
South Africa	CAPS, IEB	ZAR	Active
Eswatini	SGCSE, IGCSE, Cambridge	SZL	Active
Kenya	CBC, 8-4-4	KES	Active
Cameroon	GCE, Baccalauréat	XAF	Active
Botswana	BGCSE	BWP	Active

2. Solution Overview

2.1 Platform Components

┌─────────────────────────────────────────────────────────────────────────────┐
│                           YEBOLEARN ECOSYSTEM                               │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐             │
│  │   SCHOOL MGMT   │  │   HOME LEARNING │  │   YEBO KIDS     │             │
│  │                 │  │                 │  │                 │             │
│  │ • Admin Dashboard│ │ • Parent Portal │  │ • Watch Videos  │             │
│  │ • Teacher Portal │ │ • Child Profiles│  │ • Play Games    │             │
│  │ • Student Portal │ │ • Milestones    │  │ • Sing Songs    │             │
│  │ • Parent Portal  │ │ • Progress      │  │ • Read Stories  │             │
│  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘             │
│           │                    │                    │                       │
│           └────────────────────┼────────────────────┘                       │
│                                │                                            │
│                    ┌───────────▼───────────┐                               │
│                    │   YEBOLEARN BACKEND   │                               │
│                    │                       │                               │
│                    │ • Multi-tenant API    │                               │
│                    │ • PostgreSQL DB       │                               │
│                    │ • AI Avatar Teacher   │                               │
│                    │ • Gamification Engine │                               │
│                    │ • Payment Processing  │                               │
│                    └───────────────────────┘                               │
│                                                                             │
│  ┌─────────────────────────────────────────────────────────────────────┐   │
│  │                     PLATFORM ADMIN (SUPERADMIN)                      │   │
│  │  School provisioning • Subscription management • Platform analytics  │   │
│  └─────────────────────────────────────────────────────────────────────┘   │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

2.2 School Types Supported

Type	Ages	Grade Structure	Special Features
ECD Only	0-6	Infant → Preschool	Milestone tracking, developmental domains, character-based learning
Primary Only	6-13	Grade 1-7	Gamified learning, flashcards, AI tutoring
Secondary Only	13-18	Form 1-6	Exam prep, transcripts, career guidance
Tertiary	18+	University	Course management, research tools
Multi-Level	Mixed	All levels	Combined features across levels

2.3 Educational Stages

typescript

type EducationalStage = 
  | 'infant'           // 0-1 years
  | 'toddler'          // 1-3 years
  | 'preschool'        // 3-5 years
  | 'primary_lower'    // 5-8 years (Grade 1-3)
  | 'primary_upper'    // 8-13 years (Grade 4-7)
  | 'secondary_junior' // 13-15 years (Form 1-3)
  | 'secondary_senior' // 15-18 years (Form 4-6)
  | 'tertiary';        // 18+ years

2.4 Yebo Friends Characters

Five mascot characters that guide learning across the platform:

Character	Animal	Personality	Primary Use
Nala	🐘 Elephant	Wise, nurturing	ECD & early primary
Tembo	🦁 Lion	Brave, encouraging	Academic challenges
Zuzu	🦒 Giraffe	Curious, playful	Exploration & discovery
Kiki	🐦 Bird	Musical, creative	Songs & arts
Simba	🦛 Hippo	Calm, storytelling	Reading & stories

3. Product Architecture

3.1 Repository Structure

Repository	Technology	Description
`yebolearn-backend`	Node.js/Express/TypeScript	Core API, PostgreSQL, multi-tenant
`yebolearn-schooladmin-dashboard`	React/Vite/TypeScript	School administrator portal
`yebolearn-teacher-dashboard`	React/Vite/TypeScript	Teacher portal
`yebolearn-student-dashboard`	React/Vite/TypeScript	Student portal with gamification
`yebolearn-parent-dashboard`	React/Vite/TypeScript	Parent portal (B2B + B2C)
`yebolearn-superadmin-dashboard`	React/Vite/TypeScript	Platform admin portal
`yebolearn-hub`	React/Vite/TypeScript	Unified hub/launcher
`yebo-kids`	React/Vite/TypeScript	Children's PWA (ages 2-8)
`yebolearn-landing`	Next.js/React	Marketing website
`yebolearn-documentation`	VitePress	User documentation

3.2 Backend Architecture

yebolearn-backend/
├── src/
│   ├── config/          # Database, env config
│   ├── controllers/     # Route handlers
│   │   └── platform/    # Platform admin controllers
│   ├── middleware/      # Auth, validation, rate limiting
│   ├── routes/          # API routes
│   │   ├── platform/    # Platform admin routes
│   │   └── public/      # Public (no-auth) routes
│   ├── services/        # Business logic
│   ├── types/           # TypeScript interfaces
│   ├── utils/           # Helpers, errors, logger
│   └── validators/      # Zod schemas
├── migrations/          # SQL migrations
└── database/            # Seed scripts

3.3 Multi-Tenancy Model

School-scoped data: All school data isolated by school_id
Platform users: Separate platform_users table for YeboLearn team
JWT tokens: Include schoolId claim for automatic tenant scoping
Middleware: multiTenant.middleware.ts enforces school boundaries

3.4 Infrastructure

Cloud Run (GCP)
├── yebolearn-api (Node.js backend)
│   ├── Cloud SQL (PostgreSQL)
│   ├── Cloud Storage (media uploads)
│   └── Secret Manager (credentials)
│
Cloudflare Pages
├── yebolearn-landing
├── yebolearn-hub
├── yebolearn-*-dashboard (all frontend apps)
└── yebo-kids

4. Core Features by User Type

4.1 Student Features

Feature	Description	Tier Required
Dashboard	XP, level, streak, class rank, today's schedule	Free
Grades	View grades, averages, transcripts	Free
Attendance	View attendance history and statistics	Free
Fees	View fee balance, payment history	Free
Schedule	Daily/weekly class timetable	Free
Notifications	School announcements, grade alerts	Free
Flashcards	Study assigned flashcard decks	Basic+
AI Tutor	Ask questions, get curriculum-aligned help	Premium+
Badges	Earn achievements for academic milestones	Free
Gamification	XP, levels, daily challenges, streaks	Free

4.2 Teacher Features

Feature	Description	Tier Required
Class Management	View/manage assigned classes	Free
Attendance Marking	Mark daily attendance (single/bulk)	Free
Grade Entry	Enter grades (single/bulk)	Basic+
Student Profiles	View student details, guardians	Free
Flashcard Decks	Create/manage flashcard decks	Basic+
Assign Flashcards	Assign decks to classes	Basic+
Flashcard Analytics	View class study statistics	Premium+
Reports	Generate attendance/grade reports	Premium+
Messages	Send messages to parents	Free
Schedule	View teaching schedule	Free

4.3 Parent/Guardian Features

Feature	Description	Tier Required
Child Profiles	View all children (school + home-only)	Free
School Progress	Grades, attendance, fees for enrolled children	Free
Fee Payments	Pay fees via Stripe/MTN MoMo	Free
Messages	Communicate with teachers	Free
Home Learning	Manage home-only children (B2C)	Premium
Milestones	Track developmental milestones	Premium
Activity Tracking	View Yebo Kids app usage	Premium
Dashboard Config	Choose active child, preferences	Free

4.4 School Admin Features

Feature	Description	Tier Required
Student Management	Add/edit/delete students	Free
Staff Management	Add/edit/delete teachers, finance users	Free
Class Management	Create classes, assign teachers/students	Free
Fee Management	Create fees, assign to students/classes	Free
Payment Tracking	View all payments, reconciliation	Free
Attendance Reports	School-wide attendance analytics	Basic+
Grade Reports	School-wide academic performance	Basic+
Custom Reports	Build custom reports	Premium+
Scheduled Reports	Auto-generate recurring reports	Enterprise
Settings	School profile, academic year, terms	Free
Analytics Dashboard	School overview, trends	Basic+

4.5 Super Admin (Platform) Features

Feature	Description
School Management	Create/edit/deactivate schools
Subscription Management	Change school subscription tiers
Platform User Management	Create platform admin/manager users
Platform Analytics	Cross-school analytics, usage metrics
Audit Logs	View platform-wide audit trail
School Onboarding	Process new school applications

5. Data Models

5.1 Core Entities

Schools

sql

CREATE TABLE schools (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    code VARCHAR(50) UNIQUE NOT NULL,          -- e.g., GREENWOOD-PRI
    address TEXT,
    contact VARCHAR(50),
    email VARCHAR(255),
    subscription_tier subscription_tier DEFAULT 'free',
    is_active BOOLEAN DEFAULT true,
    
    -- Localization
    country_code VARCHAR(2) NOT NULL,          -- ISO 3166-1 alpha-2
    currency_code VARCHAR(3) NOT NULL,         -- ISO 4217
    selected_curriculum VARCHAR(50),           -- CAPS, CBC, SGCSE, etc.
    locale VARCHAR(10) DEFAULT 'en',
    timezone VARCHAR(50) DEFAULT 'UTC',
    
    -- School type
    school_type school_type NOT NULL,          -- ecd_only, primary_only, secondary_only, tertiary, multi_level
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Users

sql

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    email VARCHAR(255) NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    
    -- Profile
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    phone VARCHAR(50),
    
    -- Role & Status
    role user_role NOT NULL,                   -- super_admin, school_admin, principal, teacher, parent, student, finance
    is_active BOOLEAN DEFAULT true,
    
    -- Security
    last_login TIMESTAMP,
    token_version INTEGER DEFAULT 0,
    password_changed_at TIMESTAMP,
    failed_login_attempts INTEGER DEFAULT 0,
    account_locked_until TIMESTAMP,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(school_id, email)
);

Students

sql

CREATE TABLE students (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    
    -- Identity
    admission_number VARCHAR(50) NOT NULL,
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    date_of_birth DATE NOT NULL,
    gender gender_type,
    
    -- Academic
    class_id UUID REFERENCES classes(id),
    enrollment_date DATE NOT NULL,
    is_active BOOLEAN DEFAULT true,
    
    -- Educational stage (auto-calculated from DOB)
    educational_stage educational_stage,
    
    -- Gamification link
    user_id UUID REFERENCES users(id),         -- For student login
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(school_id, admission_number)
);

Teachers

sql

CREATE TABLE teachers (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    
    employee_number VARCHAR(50) NOT NULL,
    department VARCHAR(100),
    specializations TEXT[],                    -- Array of subjects
    qualification VARCHAR(255),
    hire_date DATE,
    is_active BOOLEAN DEFAULT true,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(school_id, employee_number)
);

Classes

sql

CREATE TABLE classes (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    
    name VARCHAR(100) NOT NULL,                -- e.g., "Grade 5A"
    grade_level VARCHAR(50) NOT NULL,          -- e.g., "Grade 5"
    section VARCHAR(10),                       -- e.g., "A"
    academic_year VARCHAR(20) NOT NULL,
    
    teacher_id UUID REFERENCES teachers(id),   -- Class teacher
    capacity INTEGER DEFAULT 30,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(school_id, name, academic_year)
);

Guardians

sql

CREATE TABLE guardians (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    user_id UUID REFERENCES users(id) ON DELETE SET NULL,
    
    -- Contact info (can exist without user account)
    email VARCHAR(255),
    first_name VARCHAR(100),
    last_name VARCHAR(100),
    phone VARCHAR(50),
    
    relationship_type relationship_type NOT NULL,  -- father, mother, guardian, grandparent, sibling, other
    is_primary BOOLEAN DEFAULT false,
    emergency_contact BOOLEAN DEFAULT false,
    is_active BOOLEAN DEFAULT true,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Student-Guardian Link

sql

CREATE TABLE student_guardians (
    student_id UUID NOT NULL REFERENCES students(id) ON DELETE CASCADE,
    guardian_id UUID NOT NULL REFERENCES guardians(id) ON DELETE CASCADE,
    is_primary BOOLEAN DEFAULT false,
    relationship relationship_type,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    PRIMARY KEY (student_id, guardian_id)
);

5.2 Academic Entities

Subjects

sql

CREATE TABLE subjects (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    
    name VARCHAR(100) NOT NULL,
    code VARCHAR(20) NOT NULL,
    description TEXT,
    grade_level VARCHAR(50),
    curriculum_framework VARCHAR(50),          -- CAPS, CBC, etc.
    
    is_active BOOLEAN DEFAULT true,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(school_id, code)
);

Attendance

sql

CREATE TABLE attendance (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    student_id UUID NOT NULL REFERENCES students(id) ON DELETE CASCADE,
    class_id UUID REFERENCES classes(id),
    
    date DATE NOT NULL,
    status attendance_status NOT NULL,         -- present, absent, late, excused
    notes TEXT,
    
    marked_by UUID REFERENCES users(id),
    marked_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(student_id, date)
);

Grades

sql

CREATE TABLE grades (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    student_id UUID NOT NULL REFERENCES students(id) ON DELETE CASCADE,
    subject_id UUID NOT NULL REFERENCES subjects(id),
    class_id UUID REFERENCES classes(id),
    
    -- Score
    score DECIMAL(5,2) NOT NULL,
    max_score DECIMAL(5,2) NOT NULL DEFAULT 100,
    grade_letter VARCHAR(5),                   -- Auto-calculated: A, B, C, etc.
    
    -- Assessment info
    assessment_type assessment_type NOT NULL,  -- quiz, test, midterm, final, assignment, project
    assessment_name VARCHAR(255),
    exam_date DATE,
    
    -- Academic period
    term VARCHAR(50),
    academic_year VARCHAR(20),
    
    graded_by UUID REFERENCES users(id),
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.3 Financial Entities

Fees

sql

CREATE TABLE fees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    
    name VARCHAR(255) NOT NULL,
    description TEXT,
    fee_type VARCHAR(50),                      -- tuition, transport, uniform, etc.
    amount DECIMAL(10,2) NOT NULL,
    due_date DATE NOT NULL,
    
    academic_year VARCHAR(20),
    term VARCHAR(50),
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Student Fees (Assignment)

sql

CREATE TABLE student_fees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    student_id UUID NOT NULL REFERENCES students(id) ON DELETE CASCADE,
    fee_id UUID NOT NULL REFERENCES fees(id) ON DELETE CASCADE,
    
    amount DECIMAL(10,2) NOT NULL,             -- Can differ from fee.amount (discounts)
    amount_paid DECIMAL(10,2) DEFAULT 0,
    status fee_status DEFAULT 'pending',       -- pending, partially_paid, paid, overdue, waived
    due_date DATE NOT NULL,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(student_id, fee_id)
);

Payments

sql

CREATE TABLE payments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    student_id UUID NOT NULL REFERENCES students(id) ON DELETE CASCADE,
    fee_id UUID REFERENCES fees(id),
    student_fee_id UUID REFERENCES student_fees(id),
    
    amount DECIMAL(10,2) NOT NULL,
    payment_method payment_method NOT NULL,    -- cash, bank_transfer, mobile_money, card, cheque
    payment_date TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    -- Transaction tracking
    transaction_id VARCHAR(255),
    external_reference VARCHAR(255),           -- Stripe/MoMo reference
    status payment_status DEFAULT 'pending',   -- pending, processing, completed, failed, refunded
    
    -- MTN MoMo specific
    phone_number VARCHAR(50),
    
    -- Metadata
    notes TEXT,
    processed_by UUID REFERENCES users(id),
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.4 Gamification Entities

Gamification Profiles

sql

CREATE TABLE gamification_profiles (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID REFERENCES schools(id) ON DELETE CASCADE,
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    
    -- Currency
    total_coins INTEGER DEFAULT 0,
    lifetime_coins INTEGER DEFAULT 0,
    
    -- Experience
    current_xp INTEGER DEFAULT 0,
    level INTEGER DEFAULT 1,
    
    -- Streaks
    current_streak INTEGER DEFAULT 0,
    longest_streak INTEGER DEFAULT 0,
    last_activity_date DATE,
    
    -- Avatar
    avatar_url TEXT,
    avatar_items TEXT[],                       -- Purchased items
    preferred_character yebo_character,        -- nala, tembo, zuzu, kiki, simba
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(user_id)
);

Achievements

sql

CREATE TABLE achievements (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    code VARCHAR(50) UNIQUE NOT NULL,
    name VARCHAR(100) NOT NULL,
    description TEXT,
    category VARCHAR(50),                      -- academic, attendance, social, streak
    
    icon_url TEXT,
    character yebo_character,                  -- Associated character
    
    -- Rewards
    coins_reward INTEGER DEFAULT 0,
    xp_reward INTEGER DEFAULT 0,
    
    -- Unlock criteria (JSON)
    criteria JSONB,
    
    -- Targeting
    educational_stage educational_stage[],     -- Which stages can earn this
    is_hidden BOOLEAN DEFAULT false,           -- Secret achievements
    is_active BOOLEAN DEFAULT true,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

User Achievements

sql

CREATE TABLE user_achievements (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    achievement_id UUID NOT NULL REFERENCES achievements(id) ON DELETE CASCADE,
    
    earned_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    progress DECIMAL(5,2) DEFAULT 100,         -- For progressive achievements
    
    UNIQUE(user_id, achievement_id)
);

Coin Transactions

sql

CREATE TABLE coin_transactions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    
    amount INTEGER NOT NULL,                   -- Positive = earned, Negative = spent
    balance_after INTEGER NOT NULL,
    transaction_type coin_transaction_type,    -- earned, spent, bonus, penalty
    source VARCHAR(50) NOT NULL,               -- quiz_complete, flashcard_session, avatar_purchase, etc.
    reference_id UUID,                         -- Link to related entity
    description TEXT,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.5 Flashcard Entities

Flashcard Decks

sql

CREATE TABLE flashcard_decks (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    created_by UUID NOT NULL REFERENCES users(id),
    
    title VARCHAR(255) NOT NULL,
    description TEXT,
    subject_id UUID REFERENCES subjects(id),
    class_id UUID REFERENCES classes(id),
    topic VARCHAR(255),
    
    difficulty_level difficulty_level,         -- easy, medium, hard
    is_public BOOLEAN DEFAULT false,           -- Visible to other schools
    is_personal BOOLEAN DEFAULT false,         -- Teacher's personal deck
    
    card_count INTEGER DEFAULT 0,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Flashcards

sql

CREATE TABLE flashcards (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    deck_id UUID NOT NULL REFERENCES flashcard_decks(id) ON DELETE CASCADE,
    
    front_content TEXT NOT NULL,               -- Question/prompt
    back_content TEXT NOT NULL,                -- Answer
    hint TEXT,
    
    media_url TEXT,
    media_type VARCHAR(50),                    -- image, audio, video
    
    card_order INTEGER DEFAULT 0,
    difficulty_level difficulty_level,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Study Sessions

sql

CREATE TABLE flashcard_study_sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    deck_id UUID NOT NULL REFERENCES flashcard_decks(id) ON DELETE CASCADE,
    
    started_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    completed_at TIMESTAMP,
    
    cards_studied INTEGER DEFAULT 0,
    cards_correct INTEGER DEFAULT 0,
    total_time_seconds INTEGER DEFAULT 0,
    
    -- Spaced repetition
    cards_due_reviewed INTEGER DEFAULT 0,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Card Reviews (Spaced Repetition)

sql

CREATE TABLE flashcard_reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    flashcard_id UUID NOT NULL REFERENCES flashcards(id) ON DELETE CASCADE,
    session_id UUID REFERENCES flashcard_study_sessions(id),
    
    confidence_level INTEGER NOT NULL,         -- 1-5 scale
    time_spent_seconds INTEGER,
    reviewed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    -- SM-2 Algorithm fields
    ease_factor DECIMAL(4,2) DEFAULT 2.5,
    interval_days INTEGER DEFAULT 1,
    repetition_count INTEGER DEFAULT 0,
    next_review_date DATE,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.6 B2C (Home Learning) Entities

Children (Home-Only)

sql

CREATE TABLE children (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    parent_id UUID NOT NULL REFERENCES users(id) ON DELETE CASCADE,
    
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    date_of_birth DATE NOT NULL,
    gender gender_type,
    
    -- Auto-calculated from DOB
    educational_stage educational_stage,
    
    -- Mode
    child_type child_type DEFAULT 'home_only', -- home_only, school_enrolled, both
    
    -- Preferences
    preferred_character yebo_character DEFAULT 'nala',
    profile_photo_url TEXT,
    screen_time_limit_minutes INTEGER DEFAULT 60,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Child School Enrollments (Link B2C → B2B)

sql

CREATE TABLE child_school_enrollments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    child_id UUID NOT NULL REFERENCES children(id) ON DELETE CASCADE,
    school_id UUID NOT NULL REFERENCES schools(id) ON DELETE CASCADE,
    student_id UUID REFERENCES students(id),   -- Link to school's student record
    
    enrollment_status VARCHAR(20) DEFAULT 'active', -- active, inactive, pending
    enrolled_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(child_id, school_id)
);

Developmental Milestones

sql

CREATE TABLE developmental_milestones (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    domain VARCHAR(50) NOT NULL,               -- physical, cognitive, language, social, emotional
    milestone_name VARCHAR(255) NOT NULL,
    description TEXT,
    
    expected_age_min_months INTEGER NOT NULL,
    expected_age_max_months INTEGER NOT NULL,
    
    indicators TEXT[],                         -- Observable behaviors
    activities TEXT[],                         -- Suggested activities
    
    is_active BOOLEAN DEFAULT true,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Child Home Milestones (Parent-Tracked)

sql

CREATE TABLE child_home_milestones (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    child_id UUID NOT NULL REFERENCES children(id) ON DELETE CASCADE,
    milestone_id UUID NOT NULL REFERENCES developmental_milestones(id),
    
    status milestone_status DEFAULT 'not_started', -- not_started, in_progress, achieved
    achieved_date DATE,
    
    reported_by UUID REFERENCES users(id),
    evidence_type VARCHAR(50),                 -- photo, video, note
    evidence_url TEXT,
    notes TEXT,
    
    ai_detected BOOLEAN DEFAULT false,         -- Auto-detected by AI
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(child_id, milestone_id)
);

App Sessions (Yebo Kids Usage)

sql

CREATE TABLE child_app_sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    child_id UUID NOT NULL REFERENCES children(id) ON DELETE CASCADE,
    
    app_name VARCHAR(50) NOT NULL,             -- yebo_kids, yebolearn_student
    device_type VARCHAR(50),
    
    session_start TIMESTAMP NOT NULL,
    session_end TIMESTAMP,
    duration_seconds INTEGER,
    
    content_consumed INTEGER DEFAULT 0,
    games_played INTEGER DEFAULT 0,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.7 Content & Media Entities

Content Library

sql

CREATE TABLE content_library (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    title VARCHAR(255) NOT NULL,
    description TEXT,
    content_type content_type NOT NULL,        -- video, audio, interactive, document, ebook, quiz, simulation, ar_vr
    
    -- Targeting
    subject VARCHAR(100),
    topic VARCHAR(255),
    educational_stage educational_stage[],
    age_min_years INTEGER,
    age_max_years INTEGER,
    
    -- Media
    thumbnail_url TEXT,
    content_url TEXT NOT NULL,
    content_urls_by_quality JSONB,             -- {"720p": "...", "1080p": "..."}
    duration_minutes INTEGER,
    file_size_bytes BIGINT,
    
    -- Metadata
    difficulty_level INTEGER DEFAULT 1,
    character yebo_character,
    language VARCHAR(10) DEFAULT 'en',
    available_languages TEXT[],
    is_downloadable BOOLEAN DEFAULT true,
    
    -- Curriculum alignment
    curriculum_framework VARCHAR(50),
    learning_objectives TEXT[],
    keywords TEXT[],
    
    -- Stats
    view_count INTEGER DEFAULT 0,
    avg_rating DECIMAL(3,2),
    is_premium BOOLEAN DEFAULT false,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.8 Platform Entities

Platform Users (YeboLearn Team)

sql

CREATE TABLE platform_users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    
    first_name VARCHAR(100) NOT NULL,
    last_name VARCHAR(100) NOT NULL,
    phone VARCHAR(50),
    
    role platform_role NOT NULL,               -- super_admin, admin, manager, support
    is_active BOOLEAN DEFAULT true,
    
    -- Security
    last_login TIMESTAMP,
    token_version INTEGER DEFAULT 0,
    password_changed_at TIMESTAMP,
    failed_login_attempts INTEGER DEFAULT 0,
    account_locked_until TIMESTAMP,
    
    created_by UUID REFERENCES platform_users(id),
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Platform Audit Logs

sql

CREATE TABLE platform_audit_logs (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    user_id UUID REFERENCES platform_users(id),
    action VARCHAR(100) NOT NULL,
    resource_type VARCHAR(50) NOT NULL,
    resource_id UUID,
    
    changes JSONB,
    ip_address INET,
    user_agent TEXT,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

5.9 Localization Entities

Countries

sql

CREATE TABLE countries (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    code VARCHAR(2) UNIQUE NOT NULL,           -- ISO 3166-1 alpha-2
    name VARCHAR(100) NOT NULL,
    flag_emoji VARCHAR(10),
    
    currency_code VARCHAR(3) NOT NULL,         -- ISO 4217
    currency_symbol VARCHAR(10),
    
    timezone VARCHAR(50) NOT NULL,
    locale VARCHAR(10) DEFAULT 'en',
    
    is_active BOOLEAN DEFAULT true,
    display_order INTEGER DEFAULT 0,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Curricula

sql

CREATE TABLE curricula (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    code VARCHAR(50) UNIQUE NOT NULL,          -- CAPS, CBC, SGCSE, GCE, etc.
    name VARCHAR(255) NOT NULL,
    description TEXT,
    grade_structure VARCHAR(100),              -- "R-12", "Form 1-5", etc.
    
    is_active BOOLEAN DEFAULT true,
    display_order INTEGER DEFAULT 0,
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

Country-Curricula (Many-to-Many)

sql

CREATE TABLE country_curricula (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    
    country_id UUID NOT NULL REFERENCES countries(id) ON DELETE CASCADE,
    curriculum_id UUID NOT NULL REFERENCES curricula(id) ON DELETE CASCADE,
    
    is_primary BOOLEAN DEFAULT false,
    grade_levels TEXT[],
    languages TEXT[],
    
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE(country_id, curriculum_id)
);

6. API Reference

6.1 Base URL

Production: https://api.yebolearn.com/api/v1
Development: http://localhost:3000/api/v1

6.2 Authentication

Endpoint	Method	Description	Auth
`POST /auth/login`	POST	Login with email/password	Public
`POST /auth/refresh`	POST	Refresh access token	Public
`POST /auth/logout`	POST	Logout (invalidate refresh token)	Public
`POST /auth/change-password`	POST	Change password	Required
`GET /auth/me`	GET	Get current user profile	Required

6.3 Students

Endpoint	Method	Description	Roles
`GET /students`	GET	List students (paginated)	All
`GET /students/:id`	GET	Get student by ID	All
`POST /students`	POST	Create student	Teacher+
`PUT /students/:id`	PUT	Update student	Teacher+
`DELETE /students/:id`	DELETE	Delete student	Teacher+
`GET /students/class/:classId`	GET	Get students by class	All

6.4 Teachers

Endpoint	Method	Description	Roles
`GET /teachers`	GET	List teachers	Admin/Principal
`GET /teachers/:id`	GET	Get teacher by ID	Admin/Principal
`POST /teachers`	POST	Create teacher	Admin/Principal
`PUT /teachers/:id`	PUT	Update teacher	Admin/Principal
`DELETE /teachers/:id`	DELETE	Delete teacher	Admin/Principal
`GET /teachers/:id/schedule`	GET	Get teacher schedule	Teacher+
`GET /teachers/:id/classes`	GET	Get teacher's classes	Teacher+
`GET /teachers/:id/stats`	GET	Get teacher statistics	Teacher+

6.5 Classes

Endpoint	Method	Description	Roles
`GET /classes`	GET	List classes	All
`GET /classes/:id`	GET	Get class by ID	All
`POST /classes`	POST	Create class	Admin/Principal
`PUT /classes/:id`	PUT	Update class	Admin/Principal
`DELETE /classes/:id`	DELETE	Delete class	Admin/Principal
`GET /classes/:id/roster`	GET	Get class roster	All
`POST /classes/:id/assign-students`	POST	Assign students	Teacher+
`POST /classes/:id/assign-teacher`	POST	Assign teacher	Admin/Principal
`GET /classes/:id/stats`	GET	Get class statistics	All

6.6 Guardians

Endpoint	Method	Description	Roles
`GET /guardians`	GET	List guardians	Teacher+
`GET /guardians/:id`	GET	Get guardian by ID	Teacher+
`POST /guardians`	POST	Create guardian	Teacher+
`PUT /guardians/:id`	PUT	Update guardian	Teacher+
`DELETE /guardians/:id`	DELETE	Delete guardian	Teacher+
`POST /guardians/:id/students`	POST	Assign student to guardian	Teacher+
`DELETE /guardians/:id/students/:studentId`	DELETE	Remove student from guardian	Teacher+
`GET /guardians/:id/students`	GET	Get guardian's students	Teacher+
`GET /guardians/students/:studentId`	GET	Get student's guardians	Teacher+

6.7 Attendance

Endpoint	Method	Description	Roles
`POST /attendance`	POST	Mark single attendance	Teacher+
`POST /attendance/bulk`	POST	Bulk mark attendance	Teacher+
`GET /attendance/student/:studentId`	GET	Get student attendance	All
`GET /attendance/class/:classId`	GET	Get class attendance	Teacher+
`GET /attendance/student/:studentId/stats`	GET	Get attendance statistics	All

6.8 Grades

Endpoint	Method	Description	Roles	Tier
`POST /grades`	POST	Enter single grade	Teacher+	Basic+
`POST /grades/bulk`	POST	Bulk enter grades	Teacher+	Basic+
`GET /grades/student/:studentId`	GET	Get student grades	All	Basic+
`GET /grades/class/:classId`	GET	Get class grades	Teacher+	Basic+
`PUT /grades/:id`	PUT	Update grade	Teacher+	Basic+
`DELETE /grades/:id`	DELETE	Delete grade	Admin/Principal	Basic+
`GET /grades/student/:studentId/average`	GET	Get student average	All	Basic+
`GET /grades/student/:studentId/transcript`	GET	Generate transcript	All	Basic+
`GET /grades/subject/:subjectId/class/:classId/performance`	GET	Subject performance	Teacher+	Basic+

6.9 Fees & Payments

Endpoint	Method	Description	Roles
`GET /fees`	GET	List fees	All
`GET /fees/:id`	GET	Get fee by ID	All
`POST /fees`	POST	Create fee	Admin/Finance
`PUT /fees/:id`	PUT	Update fee	Admin/Finance
`DELETE /fees/:id`	DELETE	Delete fee	Admin/Principal
`POST /fees/assign-student`	POST	Assign fee to student	Admin/Finance
`POST /fees/assign-class`	POST	Assign fee to class	Admin/Finance
`GET /fees/student/:studentId`	GET	Get student fees	All
`GET /fees/outstanding`	GET	Get outstanding fees	Admin/Finance
`GET /fees/overdue`	GET	Get overdue fees	Admin/Finance

Endpoint	Method	Description	Roles
`POST /payments/stripe/create-payment-intent`	POST	Create Stripe payment	Parent/Finance
`POST /payments/mtn-momo/create-payment`	POST	Create MTN MoMo payment	Parent/Finance
`POST /payments`	POST	Record manual payment	Admin/Finance
`GET /payments`	GET	List payments	Admin/Finance
`GET /payments/:id`	GET	Get payment by ID	All
`GET /payments/:id/receipt`	GET	Generate receipt	All
`PUT /payments/:id/status`	PUT	Update payment status	Admin/Finance
`POST /payments/:id/refund`	POST	Process refund	Admin/Finance
`GET /payments/stats`	GET	Payment statistics	Admin/Finance
`GET /payments/reconcile`	GET	Reconciliation report	Admin/Finance
`GET /payments/mtn-momo/status/:referenceId`	GET	Check MoMo status	All
`GET /payments/mtn-momo/balance`	GET	MoMo account balance	Admin/Finance
`POST /payments/mtn-momo/validate-account`	POST	Validate MoMo account	All

6.10 Flashcards

Endpoint	Method	Description	Roles	Tier
`POST /flashcards/decks`	POST	Create deck	Teacher	Basic+
`GET /flashcards/decks`	GET	List decks	Teacher	Basic+
`GET /flashcards/decks/:id`	GET	Get deck	All	Basic+
`PUT /flashcards/decks/:id`	PUT	Update deck	Teacher	Basic+
`DELETE /flashcards/decks/:id`	DELETE	Delete deck	Teacher	Basic+
`POST /flashcards/decks/:deckId/cards`	POST	Add card	Teacher	Basic+
`GET /flashcards/decks/:deckId/cards`	GET	Get cards	All	Basic+
`PUT /flashcards/decks/:deckId/cards/:cardId`	PUT	Update card	Teacher	Basic+
`DELETE /flashcards/decks/:deckId/cards/:cardId`	DELETE	Delete card	Teacher	Basic+
`POST /flashcards/sessions`	POST	Start study session	Student	Basic+
`PUT /flashcards/sessions/:sessionId/complete`	PUT	Complete session	Student	Basic+
`GET /flashcards/sessions`	GET	Get student sessions	Student	Basic+
`POST /flashcards/reviews`	POST	Submit card review	Student	Basic+
`GET /flashcards/reviews/due`	GET	Get due cards	Student	Basic+
`GET /flashcards/decks/:deckId/progress`	GET	Get progress	Student	Basic+
`POST /flashcards/assignments`	POST	Assign deck to class	Teacher	Basic+
`GET /flashcards/my-decks`	GET	Student's assigned decks	Student	Basic+
`GET /flashcards/analytics/deck/:deckId/class/:classId`	GET	Deck analytics	Teacher	Premium+

6.11 Avatar Teacher (AI)

Endpoint	Method	Description	Auth	Tier
`GET /avatar-teacher/health`	GET	Health check	Public	-
`GET /avatar-teacher/languages`	GET	Supported languages	Public	-
`GET /avatar-teacher/curricula`	GET	Supported curricula	Public	-
`POST /avatar-teacher/demo/math`	POST	Demo math question	Public	-
`POST /avatar-teacher/lessons/start`	POST	Start lesson session	Student	Premium+
`POST /avatar-teacher/ask`	POST	Ask text question	Student	Premium+
`POST /avatar-teacher/speak`	POST	Voice input	Student	Premium+

6.12 Reports & Analytics

Endpoint	Method	Description	Roles	Tier
`GET /analytics/overview`	GET	School overview	All	Basic+
`GET /analytics/attendance`	GET	Attendance trend	All	Basic+
`GET /analytics/fees`	GET	Fee collection trend	All	Basic+
`GET /analytics/students-by-grade`	GET	Students by grade	All	Basic+
`GET /analytics/top-classes`	GET	Top classes	All	Basic+
`GET /analytics/recent-payments`	GET	Recent payments	All	Basic+
`GET /reports/attendance`	GET	Attendance report	Admin/Principal	Premium+
`GET /reports/grades`	GET	Grades report	Teacher+	Premium+
`GET /reports/fees`	GET	Fees report	Admin/Finance	Premium+
`GET /reports/students`	GET	Students report	Admin/Principal	Premium+
`GET /reports/dashboard`	GET	Dashboard analytics	Admin/Principal	Premium+
`GET /reports/csv/:reportType`	GET	CSV export	Teacher+	Premium+
`GET /reports/scheduled`	GET	Scheduled reports	Admin/Principal	Enterprise
`POST /reports/scheduled`	POST	Create scheduled report	Admin/Principal	Enterprise
`POST /reports/custom`	POST	Generate custom report	Admin/Principal	Premium+
`POST /reports/compare`	POST	Comparative report	Admin/Principal	Premium+

6.13 Platform Admin Routes

Endpoint	Method	Description	Roles
`POST /platform/auth/login`	POST	Platform user login	Public
`POST /platform/auth/register`	POST	Create platform user	SuperAdmin
`POST /platform/auth/refresh`	POST	Refresh token	Public
`GET /platform/auth/me`	GET	Get current platform user	Platform
`GET /platform/schools`	GET	List all schools	Manager+
`POST /platform/schools`	POST	Create school	Admin+
`GET /platform/schools/:id`	GET	Get school	Manager+
`PUT /platform/schools/:id`	PUT	Update school	Admin+
`PUT /platform/schools/:id/subscription`	PUT	Update subscription	Admin+
`PUT /platform/schools/:id/status`	PUT	Toggle school status	Admin+
`GET /platform/schools/:id/stats`	GET	School statistics	Manager+
`GET /platform/analytics`	GET	Platform analytics	Manager+
`GET /platform/audit`	GET	Audit logs	Admin+

6.14 Parent B2C Routes

Endpoint	Method	Description	Auth
`GET /parent/children`	GET	List all children	Required
`POST /parent/children`	POST	Add home-only child	Required
`GET /parent/children/:id`	GET	Get child details	Required
`PUT /parent/children/:id`	PUT	Update child	Required
`DELETE /parent/children/:id`	DELETE	Remove child	Required
`GET /parent/children/:id/home-activity`	GET	Yebo Kids activity	Required
`GET /parent/children/:id/milestones`	GET	Get milestones	Required
`POST /parent/children/:id/milestones`	POST	Record milestone	Required
`GET /parent/dashboard-config`	GET	Get dashboard config	Required
`PUT /parent/dashboard-config/active-child`	PUT	Set active child	Required
`PUT /parent/dashboard-config/preferences`	PUT	Update preferences	Required

6.15 Public Routes (No Auth)

Endpoint	Method	Description
`POST /onboarding/submit`	POST	Submit school onboarding application
`GET /public/curricula`	GET	Get available curricula
`GET /public/countries`	GET	Get supported countries
`GET /countries`	GET	Get all countries
`POST /public/contact`	POST	Submit contact form

7. Yebo Kids PWA

7.1 Overview

Yebo Kids is a Progressive Web App designed for children ages 2-8, featuring:

Colorful, touch-friendly UI with large buttons
Character-based navigation with Yebo Friends mascots
Offline support via service workers
Parental controls via YeboLearn parent dashboard

7.2 Core Sections

Section	Icon	Description
Watch	🎬	Educational videos, cartoons, learning shows
Play	🎮	Interactive games, puzzles, activities
Sing	🎵	Nursery rhymes, songs, sing-alongs
Stories	📚	Animated storybooks, read-aloud stories

7.3 Features

Character Selection: Choose preferred Yebo Friend (Nala, Tembo, Zuzu, Kiki, Simba)
Star Rewards: Earn stars for completing content
Streak Tracking: Daily engagement streaks
Sticker Collection: Unlock stickers as rewards
Progress Dashboard: Daily stats for parents
Age-Appropriate Content: Filtered by educational stage
Multi-Language: English + local languages

7.4 Technical Details

yebo-kids/
├── src/
│   ├── pages/
│   │   ├── HomePage.tsx          # Main hub with sections
│   │   ├── WatchPage.tsx         # Video browser
│   │   ├── VideoDetailPage.tsx   # Video player
│   │   ├── PlayPage.tsx          # Game browser
│   │   ├── GameDetailPage.tsx    # Game player
│   │   ├── SingPage.tsx          # Song browser
│   │   ├── SongDetailPage.tsx    # Song player
│   │   ├── StoriesPage.tsx       # Story browser
│   │   └── StoryDetailPage.tsx   # Story reader
│   ├── components/
│   │   └── LandingPage/          # Landing/onboarding
│   ├── contexts/
│   │   └── ChildContext.tsx      # Child profile & rewards
│   └── lib/
│       └── api.ts                # Backend API client
├── public/
│   └── manifest.json             # PWA manifest
└── vite.config.ts                # PWA configuration

7.5 Integration with Parent Dashboard

Parents add children in Parent Dashboard
Child profiles sync to Yebo Kids
Activity tracking sent back to Parent Dashboard
Screen time limits enforced
Milestone auto-detection from content interaction

8. Dashboard Breakdown

8.1 School Admin Dashboard

URL: https://admin.yebolearn.com

Page	Features
Dashboard	Overview cards (students, teachers, fees), recent activity, quick actions
Students	Student list, search/filter, add/edit students, bulk import
Add Student	Form: personal details, class assignment, guardian linking
Staff	Teacher list, other staff, add/edit employees
Add Staff	Form: employee details, role assignment, specializations
Classes	Class list, manage rosters, assign teachers
Attendance	Mark attendance, view reports, bulk marking
Fees	Fee structures, assign to students/classes, payment tracking
Settings	School profile, academic year, terms, branding
Analytics	Charts: enrollment trends, attendance rates, fee collection

8.2 Teacher Dashboard

URL: https://teacher.yebolearn.com

Page	Features
Dashboard	Today's schedule, class overviews, pending tasks
My Classes	Assigned classes, student rosters
Attendance	Mark class attendance (single/bulk)
Grades	Enter grades, view class performance
Flashcards	Create decks, manage cards, assign to classes
Students	View student profiles, contact guardians
Messages	Send/receive messages to parents
Schedule	Weekly timetable view

8.3 Student Dashboard

URL: https://student.yebolearn.com

Page	Features
Dashboard	XP/level display, streak counter, today's schedule, grade summary, notifications
Grades	Subject grades with trends, term reports, transcripts
Attendance	Attendance calendar, statistics
Schedule	Daily/weekly timetable
Flashcards	Assigned decks, study sessions, progress tracking
AI Tutor	Chat interface with Avatar Teacher
Badges	Achievement gallery, unlocked/locked badges
Fees	Fee balance, payment history
Notifications	Announcements, grade alerts, messages
Profile	Personal info, avatar customization

8.4 Parent Dashboard

URL: https://parent.yebolearn.com

Page	Features
Dashboard	Children overview, active child selector, quick stats
Children	List all children (school + home-only), add B2C children
School Progress	Grades, attendance, fees for enrolled children
Home Learning	Yebo Kids activity, content history, screen time
Milestones	Developmental tracking, evidence upload
Fees	Outstanding balances, pay fees, receipts
Messages	Communication with teachers
Settings	Preferences, notifications, child profiles

8.5 Super Admin Dashboard

URL: https://platform.yebolearn.com

Page	Features
Dashboard	Platform overview: total schools, users, revenue
Schools	List all schools, create/edit, subscription management
School Details	School statistics, user counts, usage metrics
Users	Platform user management (admins, managers, support)
Onboarding	Pending school applications, approval workflow
Audit Logs	Platform-wide activity logs
Analytics	Cross-school analytics, trends, reports

9. Authentication & Authorization

9.1 Authentication Flow

┌─────────┐      ┌─────────┐      ┌─────────┐
│  Login  │ ───▶ │ Verify  │ ───▶ │  Issue  │
│  Form   │      │ Creds   │      │ Tokens  │
└─────────┘      └─────────┘      └─────────┘
                                       │
                     ┌─────────────────┘
                     ▼
            ┌─────────────────┐
            │  Access Token   │  (15 min expiry)
            │  Refresh Token  │  (7 day expiry)
            └─────────────────┘
                     │
                     ▼
            ┌─────────────────┐
            │   API Requests  │
            │ Authorization:  │
            │ Bearer <token>  │
            └─────────────────┘

9.2 JWT Token Structure

Access Token Payload:

json

{
  "userId": "uuid",
  "schoolId": "uuid",
  "role": "teacher",
  "email": "teacher@school.com",
  "tokenVersion": 1,
  "iat": 1700000000,
  "exp": 1700000900
}

Platform Token Payload:

json

{
  "userId": "uuid",
  "role": "admin",
  "email": "admin@yebolearn.com",
  "tokenVersion": 1,
  "iat": 1700000000,
  "exp": 1700000900
}

9.3 Role Hierarchy

School Roles:

super_admin (legacy, same as school_admin)
    │
    ├── school_admin
    │       │
    │       ├── principal
    │       │       │
    │       │       ├── teacher
    │       │       │       │
    │       │       │       └── student
    │       │       │
    │       │       └── finance
    │       │
    │       └── parent (guardian access)

Platform Roles:

super_admin (YeboLearn team lead)
    │
    ├── admin (full access)
    │
    ├── manager (read + limited write)
    │
    └── support (read-only)

9.4 Permission System

School Permissions (schoolPermissions.ts):

typescript

export const SCHOOL_PERMISSIONS = {
  // Student Management
  CREATE_STUDENT: 'create:student',
  READ_STUDENT: 'read:student',
  UPDATE_STUDENT: 'update:student',
  DELETE_STUDENT: 'delete:student',
  
  // Guardian Management
  CREATE_GUARDIAN: 'create:guardian',
  READ_GUARDIAN: 'read:guardian',
  UPDATE_GUARDIAN: 'update:guardian',
  DELETE_GUARDIAN: 'delete:guardian',
  
  // Class Management
  CREATE_CLASS: 'create:class',
  READ_CLASS: 'read:class',
  UPDATE_CLASS: 'update:class',
  DELETE_CLASS: 'delete:class',
  
  // Attendance
  MARK_ATTENDANCE: 'mark:attendance',
  READ_ATTENDANCE: 'read:attendance',
  
  // Grades
  CREATE_GRADE: 'create:grade',
  READ_GRADE: 'read:grade',
  UPDATE_GRADE: 'update:grade',
  DELETE_GRADE: 'delete:grade',
  
  // Fees & Payments
  CREATE_FEE: 'create:fee',
  READ_FEE: 'read:fee',
  UPDATE_FEE: 'update:fee',
  DELETE_FEE: 'delete:fee',
  PROCESS_PAYMENT: 'process:payment',
  READ_PAYMENT: 'read:payment',
  UPDATE_PAYMENT: 'update:payment',
  
  // Reports
  GENERATE_REPORTS: 'generate:reports',
  
  // Settings
  MANAGE_SETTINGS: 'manage:settings',
};

export const ROLE_PERMISSIONS: Record<UserRole, string[]> = {
  school_admin: Object.values(SCHOOL_PERMISSIONS),
  principal: [/* subset */],
  teacher: [/* subset */],
  finance: [/* finance subset */],
  parent: ['read:student', 'read:grade', 'read:attendance', 'read:fee', 'process:payment'],
  student: ['read:grade', 'read:attendance', 'read:fee'],
};

9.5 Middleware Chain

typescript

// Typical protected route
router.get('/students',
  authenticate,           // Verify JWT
  multiTenant,            // Extract schoolId, enforce tenant
  loadSchoolSubscription, // Load tier for feature gating
  can.readStudent,        // Check permission
  studentController.findAll
);

10. Billing & Pricing

10.1 Subscription Tiers

Feature	FREE	BASIC	PREMIUM	ENTERPRISE
Price (Monthly)	$0	$49	$199	Custom
Students	50	250	1,000	Unlimited
Teachers	5	25	100	Unlimited
Attendance	✅	✅	✅	✅
Grades	❌	✅	✅	✅
Fee Management	Basic	✅	✅	✅
Flashcards	❌	✅	✅	✅
AI Tutor	❌	❌	✅	✅
Custom Reports	❌	❌	✅	✅
Scheduled Reports	❌	❌	❌	✅
API Access	❌	❌	❌	✅
White Label	❌	❌	❌	✅
Dedicated Support	❌	Email	Phone	Account Manager

10.2 Feature Gating

typescript

// middleware/featureGate.middleware.ts

export const TIER_FEATURES: Record<SubscriptionTier, string[]> = {
  free: ['attendance', 'basic_fees', 'messaging'],
  basic: ['attendance', 'grades', 'fees', 'flashcards', 'messaging', 'basic_reports'],
  premium: ['all_basic', 'ai_tutor', 'custom_reports', 'advanced_analytics'],
  enterprise: ['all_premium', 'scheduled_reports', 'api_access', 'white_label', 'sso'],
};

export const TIER_LIMITS: Record<SubscriptionTier, { students: number; teachers: number }> = {
  free: { students: 50, teachers: 5 },
  basic: { students: 250, teachers: 25 },
  premium: { students: 1000, teachers: 100 },
  enterprise: { students: Infinity, teachers: Infinity },
};

export const checkLimits = {
  students: async (req, res, next) => {
    const { subscription } = req;
    const currentCount = await getStudentCount(req.schoolId);
    const limit = TIER_LIMITS[subscription.tier].students;
    if (currentCount >= limit) {
      return res.status(403).json({
        success: false,
        message: `Student limit reached (${limit}). Upgrade to add more students.`,
      });
    }
    next();
  },
  teachers: async (req, res, next) => {
    // Similar logic
  },
};

export const requireFeatures = {
  grades: (req, res, next) => {
    if (!TIER_FEATURES[req.subscription.tier].includes('grades')) {
      return res.status(403).json({
        success: false,
        message: 'Grades feature requires BASIC tier or above.',
      });
    }
    next();
  },
  // ... other feature gates
};

10.3 Payment Integration

Stripe:

Card payments (international)
Payment intents for secure checkout
Webhook for payment confirmation

MTN Mobile Money:

Collection API integration
Phone number validation
Push payment requests
Status polling
Webhook callbacks

11. Technical Stack

11.1 Backend

Component	Technology
Runtime	Node.js v22+
Framework	Express.js 4.x
Language	TypeScript 5.x
Database	PostgreSQL 15
ORM	Raw SQL (pg driver)
Validation	Zod
Auth	JWT (jsonwebtoken, bcrypt)
Logging	Winston
API Docs	Swagger/OpenAPI
Testing	Jest

11.2 Frontend (All Dashboards)

Component	Technology
Framework	React 18+
Build Tool	Vite 5
Language	TypeScript 5.x
Styling	Tailwind CSS 3.x
UI Components	shadcn/ui
State Management	React Context + Hooks
HTTP Client	Fetch API
Routing	React Router 6
Charts	Recharts

11.3 Infrastructure

Component	Service
Compute	Google Cloud Run
Database	Cloud SQL (PostgreSQL)
Storage	Cloud Storage
Secrets	Secret Manager
Frontend Hosting	Cloudflare Pages
DNS	Cloudflare
CDN	Cloudflare
Monitoring	Cloud Logging

11.4 External Services

Service	Purpose
Stripe	Card payments
MTN MoMo	Mobile money (Africa)
Google Gemini	AI tutoring
ElevenLabs	Text-to-speech (Avatar)
Deepgram	Speech-to-text

12. Gaps & Missing Features

12.1 Critical Gaps

Gap	Impact	Priority
No SMS notifications	Parents without smartphones miss alerts	HIGH
No offline mode	Schools with poor connectivity can't use app	HIGH
No data import	Schools can't migrate from existing systems	HIGH
No multi-language UI	Limited to English interface	MEDIUM

12.2 Feature Gaps

Feature	Description	Priority
Timetable Builder	Visual schedule creation tool	MEDIUM
Exam Scheduling	Exam calendar management	MEDIUM
Library Management	Book lending, digital resources	LOW
Transport Management	Bus routes, tracking	LOW
Hostel Management	Boarding school accommodation	LOW
Alumni Portal	Graduate tracking, networking	LOW
Parent-Teacher Conference	Meeting scheduling	MEDIUM
Digital Report Cards	PDF generation, email delivery	HIGH
Bulk SMS	SMS notification service	HIGH
WhatsApp Integration	WhatsApp notifications	MEDIUM

12.3 Technical Debt

Issue	Description	Priority
No Prisma ORM	Raw SQL queries scattered	LOW
No Redis caching	No caching layer for performance	MEDIUM
No job queue	No background job processing	MEDIUM
No E2E tests	Frontend testing missing	HIGH
No CI/CD pipeline	Manual deployments	HIGH
No error tracking	No Sentry or similar	HIGH

12.4 Yebo Kids Gaps

Gap	Description	Priority
No content CMS	Content hardcoded, no admin panel	HIGH
No parental PIN	No child lock features	MEDIUM
No offline content	Requires internet for all content	HIGH
Limited languages	Only English content	MEDIUM
No AR features	No augmented reality games	LOW

12.5 AI System Gaps

Gap	Description	Priority
No conversation history	Sessions don't persist	MEDIUM
Limited curricula	Not all topics covered	HIGH
No math rendering	LaTeX/equations display issues	MEDIUM
No image understanding	Can't analyze diagrams	LOW
No progress tracking	AI doesn't track learning path	MEDIUM

Appendix A: Enums

sql

-- User roles
CREATE TYPE user_role AS ENUM (
  'super_admin', 'school_admin', 'principal', 
  'teacher', 'parent', 'student', 'finance'
);

-- Platform roles
CREATE TYPE platform_role AS ENUM (
  'super_admin', 'admin', 'manager', 'support'
);

-- Subscription tiers
CREATE TYPE subscription_tier AS ENUM (
  'free', 'basic', 'premium', 'enterprise'
);

-- School types
CREATE TYPE school_type AS ENUM (
  'ecd_only', 'primary_only', 'secondary_only', 
  'tertiary', 'multi_level'
);

-- Educational stages
CREATE TYPE educational_stage AS ENUM (
  'infant', 'toddler', 'preschool', 
  'primary_lower', 'primary_upper', 
  'secondary_junior', 'secondary_senior', 
  'tertiary'
);

-- Yebo Friends characters
CREATE TYPE yebo_character AS ENUM (
  'nala', 'tembo', 'zuzu', 'kiki', 'simba'
);

-- Child types (B2C)
CREATE TYPE child_type AS ENUM (
  'home_only', 'school_enrolled', 'both'
);

-- Gender
CREATE TYPE gender_type AS ENUM (
  'male', 'female', 'other'
);

-- Attendance status
CREATE TYPE attendance_status AS ENUM (
  'present', 'absent', 'late', 'excused'
);

-- Fee status
CREATE TYPE fee_status AS ENUM (
  'pending', 'partially_paid', 'paid', 'overdue', 'waived'
);

-- Payment status
CREATE TYPE payment_status AS ENUM (
  'pending', 'processing', 'completed', 'failed', 'refunded'
);

-- Payment method
CREATE TYPE payment_method AS ENUM (
  'cash', 'bank_transfer', 'mobile_money', 'card', 'cheque'
);

-- Assessment types
CREATE TYPE assessment_type AS ENUM (
  'quiz', 'test', 'midterm', 'final', 'assignment', 'project'
);

-- Relationship types
CREATE TYPE relationship_type AS ENUM (
  'father', 'mother', 'guardian', 'grandparent', 'sibling', 'other'
);

-- Difficulty levels
CREATE TYPE difficulty_level AS ENUM (
  'easy', 'medium', 'hard'
);

-- Content types
CREATE TYPE content_type AS ENUM (
  'video', 'audio', 'interactive', 'document', 
  'ebook', 'quiz', 'simulation', 'ar_vr'
);

-- Milestone status
CREATE TYPE milestone_status AS ENUM (
  'not_started', 'in_progress', 'achieved'
);

-- Notification types
CREATE TYPE notification_type AS ENUM (
  'announcement', 'attendance', 'grade', 'fee', 'message', 'system'
);

-- Notification priority
CREATE TYPE notification_priority AS ENUM (
  'low', 'medium', 'high', 'urgent'
);

-- Coin transaction types
CREATE TYPE coin_transaction_type AS ENUM (
  'earned', 'spent', 'bonus', 'penalty'
);

Appendix B: Supported Curricula

Code	Name	Countries	Grade Structure
CAPS	Curriculum and Assessment Policy Statement	South Africa	R-12
IEB	Independent Examinations Board	South Africa	R-12
SGCSE	Swaziland General Certificate of Secondary Education	Eswatini	Form 1-5
IGCSE	International General Certificate of Secondary Education	Eswatini, Multi	Form 1-5
Cambridge	Cambridge International AS/A Levels	Eswatini, Multi	Form 6
CBC	Competency-Based Curriculum	Kenya	PP1-Grade 9
8-4-4	Kenya 8-4-4 System (Legacy)	Kenya	Std 1-Form 4
GCE	General Certificate of Education	Cameroon	Form 1-Upper Sixth
Baccalauréat	French Baccalauréat	Cameroon	6ème-Terminale
BGCSE	Botswana General Certificate of Secondary Education	Botswana	Form 1-5

Appendix C: API Error Codes

Code	HTTP Status	Description
`AUTH_REQUIRED`	401	No authentication token provided
`INVALID_TOKEN`	401	Token is invalid or expired
`FORBIDDEN`	403	Insufficient permissions
`FEATURE_NOT_AVAILABLE`	403	Feature requires higher tier
`LIMIT_EXCEEDED`	403	Subscription limit reached
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Request validation failed
`CONFLICT`	409	Resource already exists
`RATE_LIMITED`	429	Too many requests
`SERVER_ERROR`	500	Internal server error

Document generated from live codebase analysis. For latest updates, refer to the source repositories.

API

Backend API

Okia AI Service

Frontend

Student Dashboard

Teacher Dashboard

Parent Dashboard

School Admin Dashboard

YeboLearn - Product Requirements Document ​

Table of Contents ​

1. Vision & Problem Statement ​

1.1 The Problem ​

1.2 Our Vision ​

1.3 Target Markets ​

2. Solution Overview ​

2.1 Platform Components ​

2.2 School Types Supported ​

2.3 Educational Stages ​

2.4 Yebo Friends Characters ​

3. Product Architecture ​

3.1 Repository Structure ​

3.2 Backend Architecture ​

3.3 Multi-Tenancy Model ​

3.4 Infrastructure ​

4. Core Features by User Type ​

4.1 Student Features ​

4.2 Teacher Features ​

4.3 Parent/Guardian Features ​

4.4 School Admin Features ​

4.5 Super Admin (Platform) Features ​

5. Data Models ​

5.1 Core Entities ​

Schools ​

Users ​

Students ​

Teachers ​

Classes ​

Guardians ​

Student-Guardian Link ​

5.2 Academic Entities ​

Subjects ​

Attendance ​

Grades ​

5.3 Financial Entities ​

Fees ​

Student Fees (Assignment) ​

Payments ​

5.4 Gamification Entities ​

Gamification Profiles ​

Achievements ​

User Achievements ​

Coin Transactions ​

5.5 Flashcard Entities ​

Flashcard Decks ​

Flashcards ​

Study Sessions ​

Card Reviews (Spaced Repetition) ​

5.6 B2C (Home Learning) Entities ​

Children (Home-Only) ​

Child School Enrollments (Link B2C → B2B) ​

Developmental Milestones ​

Child Home Milestones (Parent-Tracked) ​

App Sessions (Yebo Kids Usage) ​

5.7 Content & Media Entities ​

Content Library ​

5.8 Platform Entities ​

Platform Users (YeboLearn Team) ​

Platform Audit Logs ​

5.9 Localization Entities ​

Countries ​

Curricula ​

Country-Curricula (Many-to-Many) ​

6. API Reference ​

6.1 Base URL ​

6.2 Authentication ​

6.3 Students ​

6.4 Teachers ​

6.5 Classes ​

6.6 Guardians ​

6.7 Attendance ​

YeboLearn - Product Requirements Document

Table of Contents

1. Vision & Problem Statement

1.1 The Problem

1.2 Our Vision

1.3 Target Markets

2. Solution Overview

2.1 Platform Components

2.2 School Types Supported

2.3 Educational Stages

2.4 Yebo Friends Characters

3. Product Architecture

3.1 Repository Structure

3.2 Backend Architecture

3.3 Multi-Tenancy Model

3.4 Infrastructure

4. Core Features by User Type

4.1 Student Features

4.2 Teacher Features

4.3 Parent/Guardian Features

4.4 School Admin Features

4.5 Super Admin (Platform) Features

5. Data Models

5.1 Core Entities

Schools

Users

Students

Teachers

Classes

Guardians

Student-Guardian Link

5.2 Academic Entities

Subjects

Attendance

Grades

5.3 Financial Entities

Fees

Student Fees (Assignment)

Payments

5.4 Gamification Entities

Gamification Profiles

Achievements

User Achievements

Coin Transactions

5.5 Flashcard Entities

Flashcard Decks

Flashcards

Study Sessions

Card Reviews (Spaced Repetition)

5.6 B2C (Home Learning) Entities

Children (Home-Only)

Child School Enrollments (Link B2C → B2B)

Developmental Milestones

Child Home Milestones (Parent-Tracked)

App Sessions (Yebo Kids Usage)

5.7 Content & Media Entities

Content Library

5.8 Platform Entities

Platform Users (YeboLearn Team)

Platform Audit Logs

5.9 Localization Entities

Countries

Curricula

Country-Curricula (Many-to-Many)

6. API Reference

6.1 Base URL

6.2 Authentication

6.3 Students

6.4 Teachers

6.5 Classes

6.6 Guardians

6.7 Attendance

6.8 Grades

6.9 Fees & Payments

6.10 Flashcards

6.11 Avatar Teacher (AI)

6.12 Reports & Analytics

6.13 Platform Admin Routes

6.14 Parent B2C Routes

6.15 Public Routes (No Auth)