# MADARES Online - مدارس أونلاين

## Overview
MADARES Online is a hybrid educational platform (Hybrid LMS) designed as a complete digital school. It provides advanced learning management capabilities, offering multi-curriculum education (Saudi, Egyptian, Syrian, Custom) with adaptive learning features, a Udemy-style lesson experience, and Classera-style modules. The platform aims to deliver a comprehensive and engaging online learning environment.

## User Preferences
I prefer the AI to maintain an Arabic-first communication style, reflecting the primary language of the platform. When discussing technical details, concise explanations are appreciated, focusing on architectural decisions and high-level feature specifications. For coding tasks, I prefer the agent to adhere to the established frontend (React + TypeScript + Vite, Tailwind CSS, Shadcn UI) and backend (Express.js with TypeScript) technology stack. Any proposed changes or additions should explicitly consider bilingual (Arabic/English) support and RTL implications.

## System Architecture
The platform is built with a modern web stack. The **Frontend** uses React with TypeScript and Vite, styled with Tailwind CSS and Shadcn UI components. The **Backend** is developed with Express.js and TypeScript, interacting with a PostgreSQL database via Drizzle ORM. Authentication is handled using Replit Auth (OpenID Connect).

**Key Architectural Features and Design Patterns:**
- **Hybrid LMS Design**: Integrates features of a digital school (virtual classes, attendance, timetables) with advanced LMS functionalities (adaptive learning, progress tracking).
- **Multi-Curriculum Support**: A hierarchical structure manages Curriculums, Grades, Subjects, Sections, and Lessons, allowing for diverse educational content.
- **Udemy-style Lesson Experience**: Features an interactive lesson player with tabs for Overview, Q&A, Notes, Resources, and Assessments, accompanied by a course sidebar with progress indicators.
- **Arabic-first & Bilingual UI**: Designed for RTL (Right-to-Left) with Arabic as the primary language, offering full English localization. Font choices (Cairo for Arabic, Inter for Latin) and a green-based educational color palette (hue 100) are used, with dark mode support.
- **Role-Based Access Control**: Implements distinct roles for Student, Teacher, Parent, Admin, and Supervisor, each with tailored access and functionalities.
- **Supervisor Role**: Supervisors monitor teachers and quality across assigned subjects/curricula. Features include a supervisor dashboard with stats, teacher list, and quick actions; an interactive lesson builder (slide-based lessons and educational games: match pairs, word scramble, quiz race, fill-in-the-blanks); and a student-facing interactive player at `/interactive/:id`.
- **Comprehensive Learning Tools**: Includes personal notes, Q&A forums with threaded replies, lesson bookmarks, downloadable resources, and auto-graded assessments.
- **Progress and Analytics**: Robust tracking of student progress, including dashboard statistics, weekly activity charts, study streaks, and per-subject analytics.
- **Communication & Engagement**: Features a notifications center, discussion forums (general and subject-specific), and a gamification system with badges, points, and leaderboards.
- **Content and User Management**: Admin and Teacher roles have extensive capabilities for content authoring (curricula, lessons, assessments) and user management, including subscription and attendance tracking.
- **Virtual School Mode**: Supports creation of school classes, enrollments, teacher assignments, timetables, weekly lesson plans, and parent leave request workflows.

## Authentication & Session
- **Dual Auth**: Email/password registration with email verification + OAuth (Google, Microsoft) via configurable client credentials in Settings
- **Session**: express-session with connect-pg-simple, trust proxy enabled, configurable COOKIE_SECURE and FORCE_HTTPS for cPanel HTTPS reverse proxy
- **Age-Based Role Assignment**: Configurable age threshold (default 20) in Settings. Users younger than threshold become students; older users choose teacher or parent during registration
- **OAuth Onboarding**: First-time OAuth users (no dateOfBirth/userType) see an onboarding page to complete their profile before accessing the app. The `/api/profile` endpoint returns `{ needsOnboarding: true }` for these users, and `/api/auth/complete-onboarding` processes their role assignment

## Curriculum Assignment
- Admin can assign specific curricula to students/teachers via multi-select checkboxes in user management (Add/Edit forms)
- `assignedCurricula` text[] column on `user_profiles` table stores assigned curriculum IDs
- Students/teachers see only their assigned curricula at `/curricula` (via `/api/my-curricula`); admin sees all
- Sidebar label: "منهاجي الدراسي" for student/teacher, "المناهج" for admin

## Digital Library
- **Schema**: `library_items` table with `curriculumId` column linking to curricula; `reading_progress` table tracks per-user page position (currentPage, totalPages, lastReadAt)
- **Curriculum Tabs**: Library page shows tabs per curriculum (All + each curriculum) with category filters and search
- **Admin Management**: Add/Edit/Delete books via dialog with PDF file upload + thumbnail upload; uses separate `libraryUpload` multer instance (50MB limit, allows PDF/DOC/PPT/XLS for files, images for thumbnails)
- **PDF Viewer**: `/library/view/:id` route renders PDFs using `react-pdf` with page navigation, zoom, fullscreen, sidebar, and auto-saves reading progress on page change
- **API Routes**: `GET /api/library`, `POST/PATCH/DELETE /api/admin/library`, `GET/POST /api/library/:id/progress`, `GET /api/library/progress/batch`, `GET /api/curricula/:id/subjects`
- **Dependencies**: `react-pdf`, `pdfjs-dist`

## External Dependencies
- **PostgreSQL**: Primary database for all application data.
- **Drizzle ORM**: Used for database interaction and schema definition.
- **Passport.js + Local Strategy**: Email/password auth with bcrypt hashing
- **OAuth Providers**: Google and Microsoft login (configurable via admin settings)