YeboLearn Deep Dive - Architecture

YeboLearn is a comprehensive school management and learning platform designed for the African education market. It provides role-based dashboards for students, teachers, parents, school admins, and platform super-admins, plus a dedicated Kids PWA.

Repository Structure

yebolearn/
├── backend/                    # Node.js + Express API
│   ├── src/
│   │   ├── controllers/        # Route handlers
│   │   ├── services/           # Business logic
│   │   ├── routes/             # API endpoints
│   │   ├── middleware/         # Auth, validation, etc.
│   │   ├── config/             # Database, app config
│   │   ├── utils/              # Helpers, JWT, errors
│   │   ├── types/              # TypeScript interfaces
│   │   └── validators/         # Request validation
│   └── prisma/                 # Database schema (planned)
├── dashboard-student/          # Student Portal (React)
├── dashboard-teacher/          # Teacher Portal (React)
├── dashboard-parent/           # Parent Portal (React)
├── dashboard-school-admin/     # School Admin Portal (React)
├── dashboard-super-admin/      # Platform Admin (React)
├── kids/                       # Yebo Kids PWA (React)
├── hub/                        # Central Hub/Landing
├── documentation/              # Internal docs
└── landing/                    # Marketing site

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    Load Balancer (Cloud Run)                 │
└──────────────────────────┬──────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────────┐
│                   YeboLearn Backend API                      │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │   Auth   │  │ Students │  │ Teachers │  │ Payments │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Grades  │  │Attendance│  │    AI    │  │Analytics │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
└──────────────────────────┬──────────────────────────────────┘
                           │
        ┌──────────────────┼──────────────────┐
        │                  │                  │
┌───────▼───────┐  ┌───────▼───────┐  ┌──────▼──────┐
│  PostgreSQL   │  │    Redis      │  │   Gemini    │
│  (Neon DB)    │  │   (Cache)     │  │   (AI)      │
└───────────────┘  └───────────────┘  └─────────────┘

Multi-Tenancy Model

YeboLearn uses a single-database, shared-schema multi-tenancy model:

• Each school is identified by school_id
• All user data is scoped to a school
• Platform admins have cross-school access
• Row-level security ensures data isolation

interface IUser {
  id: string;
  school_id: string;          // Tenant identifier
  email: string;
  role: UserRole;
  first_name: string;
  last_name: string;
  is_active: boolean;
}

Authentication Flow

1. School User Login

   • Email/password authentication
   • JWT with school_id and role claims
   • Token versioning for invalidation
   • Account lockout after failed attempts

2. Platform Admin Login

   • Separate authentication endpoint
   • Cross-school access permissions
   • Audit logging

// JWT Payload Structure
interface IJwtPayload {
  userId: string;
  schoolId: string;
  role: UserRole;
  email: string;
  tokenVersion: number;  // For invalidation
}

Database Layer

Uses raw PostgreSQL via pg Pool (not Prisma):

class Database {
  private pool: Pool;

  async query<T>(text: string, params?: unknown[]): Promise<QueryResult<T>> {
    // Executes parameterized queries
  }

  async transaction<T>(callback: (client: PoolClient) => Promise<T>): Promise<T> {
    // BEGIN -> callback -> COMMIT/ROLLBACK
  }
}

Key Integrations

Service	Purpose
Gemini AI	AI tutor, essay grading, lesson plans
Redis	Session cache, AI response cache
Cloudflare R2	Media storage (images, documents)
YeboLink	SMS/WhatsApp notifications

Role-Based Access

Role	Access Level
student	Own data, classes, grades
teacher	Own classes, student grades
parent	Children's data only
school_admin	Full school access
super_admin	Platform-wide access

Sub-Projects Connection

┌─────────────────────────────────────────────────────────────┐
│                     Backend API (Port 8080)                  │
└─────────────────────────────┬───────────────────────────────┘
                              │
        ┌─────────────────────┼─────────────────────┐
        │                     │                     │
┌───────▼───────┐   ┌────────▼────────┐   ┌───────▼───────┐
│ Student Portal│   │ Teacher Portal  │   │ Parent Portal │
│ (kids.yebo..) │   │ (teacher.yebo..)│   │ (parent.yebo.)│
└───────────────┘   └─────────────────┘   └───────────────┘
        │                     │                     │
        └─────────────────────┼─────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Yebo Kids PWA   │
                    │ (Mobile-first app)│
                    └───────────────────┘

All frontends:

• Share the same API
• Use JWT for authentication
• Have role-specific middleware on backend
• Can be hosted on Cloudflare Pages