Built for the Arab Academy for Science, Technology & Maritime Transport (AAST)
ClassroomX is a full-stack, AI-driven Learning Management System that transforms traditional classrooms into intelligent, data-rich environments. Using a live computer vision pipeline — powered by YOLOv8 for face detection and HSEmotion for emotion recognition — ClassroomX automatically tracks student attendance, monitors engagement, and generates per-student emotion timelines throughout every lecture.
The platform is built around a lecture state machine that coordinates real-time AI processing, WebSocket streaming, and post-session analytics reporting. It serves three distinct user groups: Administrators who manage the institution, Lecturers who run live sessions from a command-center dashboard, and Students who access their records through a React Native mobile app.
ClassroomX was developed as a graduation project at the Arab Academy for Science, Technology & Maritime Transport (AAST) and is fully deployed on Digital Ocean App Platform.
🌐 Live Application: https://classroomx-lkbxf.ondigitalocean.app/
| Login Page | Admin Panel |
|---|---|
 |
 |
| User Roster | Lecturer Dashboard |
|---|---|
 |
 |
| Live Recognition |
|---|
 |
| Feature | Description |
|---|---|
| User Management | Full CRUD for admins, lecturers, and students |
| Photo Enrollment | Upload student photos for AI face encoding into the recognition database |
| Course Management | Create and manage courses, assign lecturers and students |
| Faculty Assignment | Organize classes and faculty-level groupings |
| Class Scheduling | Define lecture schedules with automatic state transitions |
| Feature | Description |
|---|---|
| 2-Column Live Layout | Real-time classroom video feed alongside a dynamic attendance grid |
| Live Snapshots | Profile pictures automatically replaced by live recognition frames as students are identified |
| Emotion Heatmaps | Real-time visual breakdown of student emotions across the class |
| Engagement Metrics | Aggregated attention and engagement scores updated continuously |
| Hard Reset | Surgical session restart that clears state without ending the lecture |
| WebSocket Streaming | Low-latency, bidirectional data channel for live vision output |
| Feature | Description |
|---|---|
| Attendance Records | View personal attendance history per course and lecture |
| Emotion Reports | Per-lecture emotion and engagement analytics timeline |
| Course Schedule | Up-to-date class schedule with live session status indicators |
| Course Materials | Access uploaded resources and lecture content |
| Feature | Description |
|---|---|
| Face Detection | YOLOv8 model detects faces in real-time from the classroom camera feed |
| Emotion Classification | HSEmotion classifies 8 emotions per detected face per frame |
| Face Recognition | Face encodings match detected faces to the enrolled student database |
| Emotion Timeline | Per-student emotion log accumulated throughout the entire lecture duration |
| Attendance Automation | Recognition event triggers automatic attendance marking |
Every lecture in ClassroomX progresses through a strict three-phase lifecycle managed by a server-side state machine:
┌─────────────────────────────────────────────────────────────────────┐
│ LECTURE STATE MACHINE │
│ │
│ ┌───────────────┐ ┌──────────────┐ ┌─────────────┐ │
│ │ not_started │──────▶│ live │──────▶│ ended │ │
│ │ │ │ │ │ │ │
│ │ • Scheduled │ │ • AI Vision │ │ • Frozen │ │
│ │ • Waiting │ │ • WebSockets│ │ • Reports │ │
│ │ • No data │ │ • Emotions │ │ • Analysis │ │
│ └───────────────┘ │ • Attendance│ └─────────────┘ │
│ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
| State | Description | Active Systems |
|---|---|---|
not_started |
Lecture is scheduled and waiting for the lecturer to begin | None — data is static |
live |
Session is active; AI vision and WebSocket streams are running | YOLOv8, HSEmotion, WebSocket, face encoding |
ended |
Session concluded; state is frozen for post-session analysis | Report generation, engagement + attendance export |
┌─────────────────────────────────────────────────────────┐
│ CLIENT LAYER │
│ ┌────────────────┐ ┌────────────────────────┐ │
│ │ R / Shiny App │ │ React Native (Mobile) │ │
│ │ Admin Portal │ │ Student App │ │
│ │ Lecturer Dash │ │ │ │
│ └───────┬────────┘ └──────────┬─────────────┘ │
└──────────┼───────────────────────────────┼───────────────┘
│ HTTP / WebSocket │ HTTP / REST
┌──────────▼───────────────────────────────▼───────────────┐
│ FASTAPI BACKEND (Python 3.13) │
│ SQLAlchemy 2.0 ORM │ BCrypt Auth │
│ Lecture State Machine │ WebSocket Manager │
└──────────────────────┬───────────────────────────────────┘
│
┌────────────▼────────────┐
│ PostgreSQL 15+ │
│ (Digital Ocean Managed)│
└─────────────────────────┘
│
┌────────────▼────────────┐
│ Vision Pipeline │
│ YOLOv8 + HSEmotion │
│ Face Encoding Engine │
└─────────────────────────┘
| Layer | Technology | Version | Purpose |
|---|---|---|---|
| Backend API | FastAPI | Latest | REST API + WebSocket server |
| Language | Python | 3.13 | Core backend runtime |
| ORM | SQLAlchemy | 2.0 | Database models and queries |
| Database | PostgreSQL | 15+ | Persistent data store |
| DB Host | Digital Ocean Managed DB | — | Cloud-managed PostgreSQL |
| Auth | BCrypt | — | Password hashing and verification |
| Face Detection | YOLOv8 (Ultralytics) | v8 | Real-time face bounding boxes |
| Emotion Recognition | HSEmotion | — | 8-class emotion classification |
| Admin/Lecturer UI | R + Shiny | Latest | Web portal frontend |
| Student App | React Native | Latest | Cross-platform mobile app |
| Deployment | Digital Ocean App Platform | — | Cloud hosting and scaling |
The ClassroomX vision pipeline runs continuously during a live lecture session:
Classroom Camera
│
▼
┌─────────────┐
│ YOLOv8 │ ──▶ Detects face bounding boxes in each frame
│ Face Det. │
└──────┬──────┘
│ Cropped face regions
▼
┌─────────────┐
│ HSEmotion │ ──▶ Classifies 8 emotions per face:
│ Classifier │ 😊 Happy 😢 Sad 😠 Angry 😨 Fear
└──────┬──────┘ 😲 Surprise 🤢 Disgust 😐 Neutral 🤔 Contempt
│ Emotion label + confidence
▼
┌─────────────┐
│ Face │ ──▶ Matches face embedding to enrolled student
│ Encoding │ database using cosine similarity
└──────┬──────┘
│ Identified student + emotion
▼
┌─────────────┐
│ State │ ──▶ Updates:
│ Machine │ • Attendance record (first recognition)
└──────┬──────┘ • Per-student emotion timeline entry
│
▼
┌─────────────┐
│ WebSocket │ ──▶ Streams live recognition events to Lecturer Dashboard
│ Broadcast │ (attendance grid + live snapshot update)
└─────────────┘
- Python 3.13+
- R 4.x + Shiny package
- PostgreSQL 15+ (or Digital Ocean Managed DB)
- Node.js + React Native CLI (for mobile app)
git clone https://github.com/4awmy/ClassroomX.git
cd ClassroomXcd python-api
# Create and activate virtual environment
python -m venv venv
venv\Scripts\activate # Windows
# source venv/bin/activate # macOS/Linux
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env with your DATABASE_URL and other settings
# Start the API server
python main.pyThe API will be available at http://localhost:8000. Swagger docs at http://localhost:8000/docs.
# Install required R packages
install.packages(c("shiny", "httr2", "jsonlite", "DT", "bslib"))
# Set your environment variables
# Edit .Renviron with API_BASE_URL and credentials
# Launch the portal
shiny::runApp('shiny-app')cd react-native-app
# Install dependencies
npm install
# Start Metro bundler
npx react-native start
# Run on Android
npx react-native run-android
# Run on iOS
npx react-native run-ios| Variable | Description | Example |
|---|---|---|
DATABASE_URL |
PostgreSQL connection string | postgresql://user:pass@host:5432/classroomx |
SECRET_KEY |
JWT / session secret key | your-secret-key-here |
ALGORITHM |
JWT signing algorithm | HS256 |
ACCESS_TOKEN_EXPIRE_MINUTES |
Token expiry duration | 60 |
VISION_CONFIDENCE_THRESHOLD |
Min YOLOv8 confidence for face detection | 0.6 |
FACE_MATCH_THRESHOLD |
Cosine similarity cutoff for face recognition | 0.5 |
| Variable | Description | Example |
|---|---|---|
API_BASE_URL |
FastAPI backend base URL | https://classroomx-lkbxf.ondigitalocean.app |
ADMIN_USERNAME |
Default admin login | admin |
ADMIN_PASSWORD |
Default admin password | ***** |
ClassroomX/
│
├── python-api/ # FastAPI backend
│ ├── main.py # Application entry point
│ ├── models/ # SQLAlchemy ORM models
│ ├── routers/ # API route handlers
│ ├── services/ # Business logic layer
│ ├── vision/ # YOLOv8 + HSEmotion pipeline
│ ├── websockets/ # Real-time WebSocket manager
│ └── requirements.txt
│
├── shiny-app/ # R/Shiny admin & lecturer portal
│ ├── app.R # Main Shiny application
│ ├── ui/ # UI component modules
│ └── server/ # Server logic modules
│
├── react-native-app/ # React Native student mobile app
│ ├── App.tsx
│ ├── screens/
│ └── components/
│
└── docs/
└── screenshots/ # Application screenshots
├── admin_panel.png
├── admin_users.png
├── lecturer_dashboard.png
└── live_recognition.jpg
| Name | Role |
|---|---|
| Omar Hossam | Lead Developer — Backend, Vision Pipeline, Architecture |
| Team | Frontend (Shiny & React Native), Integration, Testing |
Developed as a graduation project at:
🏛️ Arab Academy for Science, Technology & Maritime Transport (AAST)
| Resource | URL |
|---|---|
| 🌐 Live Application | classroomx-lkbxf.ondigitalocean.app |
| 📦 GitHub Repository | github.com/4awmy/ClassroomX |
| 📚 API Docs (Swagger) | /docs |
This project is developed for academic purposes at AAST. All rights reserved by the authors.
Built with ❤️ at AAST · Powered by FastAPI, YOLOv8, HSEmotion, R/Shiny & React Native