Adam1230/educational-environment

🎓 Educational Training Environment — بيئة تدريبية

A modern, gamified educational training platform built for PhD research. Rebuilt with FastAPI + Tailwind CSS + Alpine.js + SQLite → deployed on Hugging Face Spaces (Docker).

   

📁 Project Structure

edu-app/
├── Dockerfile                  # Docker config for HF Spaces
├── requirements.txt            # Python dependencies
├── README.md
├── LICENSE
└── app/
    ├── __init__.py
    ├── main.py                 # FastAPI routes & app entry point
    ├── database.py             # SQLAlchemy + SQLite setup
    ├── auth.py                 # JWT auth + bcrypt password hashing
    ├── static/
    │   └── Photo/              # All original image assets (86 files)
    └── templates/
        ├── login.html          # Login + Register page (Alpine.js)
        ├── dashboard.html      # Main dashboard with all tabs
        ├── module1.html        # Module 1 — Technology Integration Concepts
        ├── module2.html        # Module 2 — Educational Video Production
        ├── module3.html        # Module 3 — Google Forms Assessment
        ├── module4.html        # Module 4 — Digital Communication & Collaboration
        ├── questions.html      # Pre-assessment test (15 questions)
        └── questions2.html     # Post-assessment test (15 questions)

🚀 Step-by-Step Deployment on Hugging Face Spaces

Step 1 — Create a Hugging Face Account

1. 1.Go to https://huggingface.co and sign up (free).
2. 2.Verify your email address.

Step 2 — Create a New Space

1. 1.Click your profile icon (top-right) → "New Space".
2. 2.Fill in the form:
3. 3.Space name: educational-environment (or any name you like)
4. 4.License: MIT
5. 5.SDK: Select "Docker" ← CRITICAL
6. 6.Visibility: Public (free) or Private (Pro plan)
7. 7.Click "Create Space".

Step 3 — Enable Persistent Storage (Important!)

1. 1.In your Space, go to Settings tab.
2. 2.Scroll to "Persistent Storage".
3. 3.Click "Add Persistent Storage" → choose Small (20GB) (free tier).
4. 4.The persistent volume will be mounted at /data — our app uses /code/data for SQLite.

⚠️ Without persistent storage, user accounts reset every time the Space restarts!

Step 4 — Upload Your Files

Option A — Via Hugging Face Web UI (Easiest):

1. 1.In your Space, click the "Files" tab.
2. 2.Click "Add file" → "Upload files".
3. 3.Upload the entire edu-app/ folder contents:
4. 4.Drag & drop Dockerfile, requirements.txt, README.md, LICENSE
5. 5.Then upload the app/ folder (with all subfolders)
6. 6.Commit the files.

Option B — Via Git (Recommended for updates):

# Clone your space
git clone https://huggingface.co/spaces/YOUR_USERNAME/educational-environment
cd educational-environment

# Copy your project files
cp -r /path/to/edu-app/* .

# Configure Git LFS for large files (images)
git lfs install
git lfs track "*.jpg" "*.jpeg" "*.png" "*.jfif" "*.gif"
git add .gitattributes

# Push everything
git add .
git commit -m "Initial deployment of Educational Training Environment"
git push

Step 5 — Set Environment Variables (Optional but Recommended)

1. 1.In your Space → Settings → "Repository secrets".
2. 2.Add: | Key | Value | |-----|-------| | SECRET_KEY | your-super-secret-jwt-key-change-this-in-production | | DB_DIR | /data |

If DB_DIR is not set, the app defaults to /code/data.

Step 6 — Wait for Build

1. 1.After pushing, HF Spaces will automatically build the Docker image.
2. 2.Build takes ~2-5 minutes.
3. 3.Monitor progress in the "Logs" tab.
4. 4.When you see Application startup complete, your app is live! 🎉

Step 7 — Access Your App

• —Your app URL: https://YOUR_USERNAME-educational-environment.hf.space
• —The login page will appear — register a new account and start!

🔧 Local Development

# 1. Clone or download this repo
git clone https://huggingface.co/spaces/YOUR_USERNAME/educational-environment
cd educational-environment

# 2. Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 3. Install dependencies
pip install -r requirements.txt

# 4. Create data directory
mkdir -p /code/data
# Or set custom path:
export DB_DIR="./data"

# 5. Run the app
uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 6. Open browser
# → http://localhost:8000

🛡️ Authentication System

• —Registration: POST /api/register — username, email, password (bcrypt hashed)
• —Login: POST /api/login — returns JWT stored in HttpOnly cookie
• —Logout: POST /api/logout — clears the cookie
• —Session: JWT token valid for 7 days
• —Protected routes: All pages except / require valid JWT cookie

Database Schema (SQLite)

CREATE TABLE users (
    id             INTEGER PRIMARY KEY AUTOINCREMENT,
    username       VARCHAR(50)  UNIQUE NOT NULL,
    email          VARCHAR(100) UNIQUE NOT NULL,
    hashed_password VARCHAR(200) NOT NULL,
    created_at     DATETIME DEFAULT CURRENT_TIMESTAMP
);

🎨 Tech Stack

📋 API Endpoints

📖 Content Flow (Pedagogical Structure)

Login/Register
    │
    ▼
Dashboard
    ├── 🏠 Home — Researcher & Supervisors intro
    ├── 🎯 Objectives — Training environment goals
    ├── 📖 Guide — 3-section learner guide with 16-step walkthrough
    ├── 📅 Pre-Assessment → /questions (15 Qs: MCQ + T/F)
    │
    ├── 📚 Content
    │   ├── 📘 Module 1 — Technology Integration Concepts (3 lessons)
    │   ├── 📕 Module 2 — Educational Video Production (3 lessons)
    │   ├── 📙 Module 3 — Google Form Assessment (3 lessons)
    │   └── 📗 Module 4 — Digital Communication (3 lessons)
    │
    ├── 📅 Post-Assessment → /questions2 (15 Qs: MCQ + T/F)
    └── 📬 Contact — Researcher info

Each lesson contains:

1. 1.Introduction — Context and overview
2. 2.Objectives — Learning targets (infographic)
3. 3.Content — Core material
4. 4.Steps/Tools — Practical application
5. 5.Activity — Hands-on task (submit to unlock next section)
6. 6.Self-Evaluation — 5-question quiz (≥50% to pass)
7. 7.Achievement Badge — Gamification reward

🐛 Troubleshooting

📄 License

MIT License — Copyright (c) 2025 Khloud Gamal Abu-Bakr

Free to use, modify, and distribute with attribution.

👩‍🎓 About

Built for the PhD research of Khloud Gamal Abu-Bakr, Teaching Assistant at the Department of Educational Technology, Faculty of Specific Education, Zagazig University, Egypt.

Research Title: The Effect of Different Challenge Patterns in a Gamification-Based Training Environment on Developing Technology Integration Skills among Faculty Members.

Supervisors:

• —Prof. Amal El-Sayed Ahmed El-Taher
• —Prof. Naglaa Saeed Mohammed
• —Dr. Lamia Mohammed El-Hadi