AI Academy - Platform Guide

Version 2.0 | Last Updated: February 2026

What Is AI Academy?

AI Academy is an English-Arabic vocabulary learning platform designed for language schools and private tutoring centers. Teachers upload lesson materials as PDF files, and the platform automatically generates interactive learning content at multiple difficulty levels.

The core idea: one PDF upload creates a complete lesson with vocabulary, games, and difficulty-adapted versions -- saving teachers hours of manual content preparation.

Who Is It For?

Teachers / Admins

Upload PDF lesson materials (textbook pages, worksheets, handouts)
The system extracts vocabulary automatically using AI
Review, edit, and manage lesson content
Assign students to appropriate difficulty levels
Track student progress across games

Students

Log in with their name and phone number (no password needed)
See lessons matched to their English level
Play three types of vocabulary games per lesson
Track their own completion progress

Platform Features

1. PDF Upload and Automatic Lesson Creation

Teachers upload a PDF document and the platform does the rest:

Text extraction from both digital and scanned PDFs (supports Arabic and English OCR)
AI-powered analysis identifies the lesson topic, learning objectives, and vocabulary pairs
Vocabulary extraction pulls out English-Arabic word pairs from the document
Lesson summary is generated automatically in markdown format
Three interactive games are created from the vocabulary
Difficulty-adapted versions are generated for all CEFR levels

The entire process runs in the background with a real-time progress bar showing each step.

2. CEFR Multi-Level System

Every lesson is available at five internationally recognized difficulty levels:

Level	Name	Description	Example Vocabulary
A1	Beginner	Most basic words, simple sentences	helper, worker, player
A2	Elementary	Everyday vocabulary, short sentences	teacher, driver, farmer
B1	Intermediate	Broader vocabulary, abstract ideas	instructor, operator, performer
B2	Upper Intermediate	Academic vocabulary, complex sentences	manufacturer, researcher, administrator
C1	Advanced	Sophisticated vocabulary, nuanced language	practitioner, entrepreneur, connoisseur

How it works: When a teacher uploads a lesson (say, at A2 level about the "-er" suffix), the AI generates four additional versions at A1, B1, B2, and C1. Each version teaches the same concept but uses vocabulary appropriate for that difficulty level. This is conceptual adaptation, not simple word filtering.

Teacher controls:

Switch between all five versions to review content
Edit vocabulary, lesson summary, or objectives for any version
Compare two versions side-by-side with the diff tool
Regenerate any version if the quality isn't satisfactory
Set which version students see by default

3. Vocabulary Scoring and Audit

Every word in the system is objectively scored for its CEFR difficulty level using two academic databases:

EFLLex (primary) -- A curated database of 100,000+ English words with CEFR classifications used in academic research
wordfreq (fallback) -- Word frequency analysis across billions of words of text

Each word receives:

A predicted CEFR level (A1 through C1)
A confidence score (0-100%) indicating how certain the classification is
A source tag showing which database was used

Teachers can view the full vocabulary audit for any lesson, filter by confidence level, and identify words that may be misclassified. Low-confidence words are flagged for manual review.

4. Interactive Games

Three game types are automatically generated for every lesson version:

Word Match

Floating bubbles with English and Arabic words
Tap two matching words to score points
Sound effects, confetti celebrations, and score tracking
10 word pairs per game (20 bubbles total)

Flashcards

Flip cards to reveal the Arabic translation
Mark words as "known" or review again
Navigate forward and backward through the deck
Score based on percentage of words marked known

Fill in the Blank

Multiple choice questions: given an English word, select the Arabic translation
Up to 15 questions per game
Immediate visual feedback (green for correct, red for incorrect)
Running score percentage displayed throughout

All games track completion status and scores. Students see checkmarks on games they've completed.

5. User Management

Three user roles:

Role	Capabilities
Super Admin	Full system access, can create other admins, cannot be deleted
Admin / Teacher	Upload lessons, manage content, create students, view all data
Student	View assigned lessons, play games, track own progress

Student accounts use phone-based login (name + country code + phone number). No password required -- designed for young learners who may not remember complex credentials.

Admin accounts use traditional username/password authentication.

Teachers can:

Create and manage student accounts
Assign CEFR levels to students
Set target CEFR levels (goals)
Search and filter the user list

6. Bilingual Interface

The entire platform supports both English and Arabic with a language switcher in the sidebar. Arabic mode activates right-to-left (RTL) layout throughout the application.

7. File Management

The Files page provides a complete document library:

Preview uploaded PDFs directly in the browser
Download original files
View processing status (Processed / Processing / Failed)
Delete documents (cascading cleanup of all associated data)

How Teachers Use the Platform

Uploading a New Lesson

Click the yellow Upload PDF button
Drag-and-drop or browse for a PDF file (up to 10MB)
Watch the progress bar as the system processes the document
When complete, view the lesson summary with extracted vocabulary and generated games

Reviewing and Editing Content

Open any lesson from the home page
The Teacher Actions panel (amber banner) provides all editing tools:
- Edit Content -- Change the topic, objectives, or lesson narrative
- Edit Vocabulary -- Add, remove, or modify English-Arabic word pairs
- Vocab Audit -- Review CEFR classifications and confidence scores
- Compare Versions -- Side-by-side diff of two CEFR versions
- Regenerate Version -- Re-generate a version with custom constraints
- Set as Default -- Choose which version students see

Managing CEFR Versions

Use the Version Switcher (tabs at the top of the lesson page) to browse A1 through C1
Each version shows its own vocabulary, word count, and lesson narrative
Click Compare Versions to see differences between any two levels
If a version needs improvement, click Regenerate and optionally provide:
- Target word count range
- Percentage of new words vs. shared words
- A concept hint to guide the AI

Setting Up Students

Go to the Users page
Click Create User and select the "Student" role
Assign a CEFR level (A1-C1) based on the student's proficiency
The student can now log in with their phone number and will see lessons at their level

How Students Use the Platform

Log in with name, country code, and phone number
Browse lessons on the home page (filtered to their CEFR level)
Open a lesson to see the overview, vocabulary preview, and available games
Play games -- Word Match, Flashcards, or Fill in the Blank
Track progress -- completed games show checkmarks, scores are recorded

Students see a simplified interface with no editing controls or administrative features.

Application Structure

Pages Overview

Page	Who Sees It	What It Does
Home (My Courseware)	Teachers	Grid of all uploaded lessons with CEFR filter, edit/delete controls, game links
Home (My Lessons)	Students	Read-only lesson grid filtered by student's CEFR level
Lesson Detail	Everyone	Full lesson view: summary, objectives, vocabulary, games, version switcher
Game Player	Everyone	Full-screen immersive game experience
Upload	Teachers	PDF upload with real-time processing progress
Files	Teachers	PDF library with preview, download, and delete
Users	Teachers	User management (create, edit, delete, assign CEFR levels)
Version Review	Teachers	Overview of all CEFR versions for a lesson with approval controls

System Architecture (Simplified)

Teacher uploads PDF
       |
       v
  AI Processing Pipeline
  (Text Extraction -> Lesson Analysis -> Vocabulary Extraction -> Scoring)
       |
       v
  Base Lesson Created (with scored vocabulary)
       |
       v
  CEFR Adapter generates 4 more versions (A1, A2, B1, B2, C1)
       |
       v
  Game Generator creates 3 games per version (15 games total)
       |
       v
  Students play games at their assigned level

Bug Fixes and Improvements (Recent)

Content Quality Fixes

Vocabulary scoring accuracy -- Fixed the CEFR scoring algorithm that was incorrectly classifying basic words (like "I", "you", "we") as B2/C1 level. The system now correctly identifies these as A1 words.
Confidence scores -- Fixed confidence calculation that showed unintuitive low scores (29%) for common words. Scores now reflect how strongly a word belongs to its assigned level (common words show ~100%).
Lesson narrative quality -- Each CEFR version now gets its own unique "About This Lesson" summary written at the appropriate language level, instead of all versions sharing the same text.
Markdown rendering -- Fixed the lesson summary display that was showing raw formatting characters instead of properly rendered text.
JSON parsing errors -- Fixed an issue where B1 and C1 versions would fail to generate due to special characters in the AI's response.

Game Fixes

Game generation per version -- Games are now generated separately for each CEFR version with level-appropriate vocabulary, not shared across all versions.
Game navigation -- Added "Next Game" and "Back to Lesson" buttons so players can move between games without returning to the lesson page.
Completion tracking -- All three game types now properly track and display completion status with animated modals.
CEFR color coding -- Game cards on the lesson page now show color-coded CEFR level badges matching the system-wide color scheme.
Game regeneration -- Added the ability to regenerate games for existing lessons if the original generation had issues.

User Interface Fixes

Upload progress bar -- Fixed the progress bar that would show 5% instead of 100% on completion.
CEFR filter -- Fixed the home page filter that wasn't properly grouping and displaying lessons by CEFR level.
Version switcher -- Fixed version navigation between CEFR levels on the lesson page.
Removed broken buttons -- Cleaned up deprecated UI elements that no longer worked.

System Reliability

Auto-scoring during ingestion -- Vocabulary is now automatically scored for CEFR level during the upload process, so the audit is immediately available.
Error recovery -- Added a retry system that can resume failed processing from the exact step that failed, without reprocessing the entire document.
Cascade deletion -- Fixed several issues with document deletion that would leave orphaned data in the database.
OCR fallback chain -- If one AI provider fails during text extraction, the system automatically tries the next available provider.

Supported AI Providers

The platform supports multiple AI providers for flexibility and cost optimization:

Provider	Used For	Tier
Mistral AI	Text analysis, lesson extraction	Free tier available
Groq	OCR / Vision processing	Free tier available
Google Gemini	Fallback provider	Free tier available
OpenAI	Optional alternative	Paid
OpenRouter	Multi-model gateway	Varies
Anthropic	Optional alternative	Paid

The system is configured to use free-tier providers by default, making it accessible for pilot programs and small deployments.

Deployment

The platform is deployed on Railway (cloud hosting) with:

PostgreSQL database for all application data
Docker container for the application (frontend and backend in one package)
Automatic migrations on deploy
Health monitoring at /health

Local development is also supported with SQLite for quick setup.

What's Next (Planned Features)

Based on the business requirements document, the following features are planned for future development:

Child-friendly UI redesign -- More colorful, playful interface with illustrations and animations designed for young learners (ages 7-14)
New game types -- Memory Match, Speed Challenge, Word Scramble, Story Builder, and Pronunciation Practice
Teacher Portal -- Class management, lesson assignments, and analytics dashboard
Progress Dashboard -- Visual learning paths, vocabulary mastery tracking, and milestone system
Text-to-Speech -- Browser-based pronunciation for English and Arabic words
Mobile optimization -- PWA support for installable mobile experience
Achievements system -- Points, badges, and rewards for student engagement
Knowledge summaries -- Auto-generated key points and concept maps

Glossary

Term	Meaning
CEFR	Common European Framework of Reference for Languages -- the international standard for describing language ability (A1 to C2)
A1-C1	Proficiency levels from Beginner (A1) to Advanced (C1)
EFLLex	English as a Foreign Language Lexicon -- an academic database mapping English words to CEFR levels
OCR	Optical Character Recognition -- converting images of text into actual text data
Conceptual Adaptation	Generating vocabulary that teaches the same concept at different difficulty levels (not just filtering words)
Vocabulary Audit	A quality review showing each word's CEFR classification, confidence score, and data source
Default Version	The CEFR version of a lesson that students see when they open it

AI Academy is built for 51Talk and English language education centers. For technical documentation, see README.md.

Mo-Atef-r/AI Academy Overview.md

Select an option

No results found